diff options
| -rw-r--r-- | general/event/README.md | 16 | ||||
| -rw-r--r-- | general/filehistory/README.md | 13 | ||||
| -rw-r--r-- | general/ioctl/kmdf/README.md | 22 | ||||
| -rw-r--r-- | general/ioctl/wdm/README.md | 16 | ||||
| -rw-r--r-- | general/obcallback/README.md | 17 | ||||
| -rw-r--r-- | general/pcidrv/README.md | 61 |
6 files changed, 43 insertions, 102 deletions
diff --git a/general/event/README.md b/general/event/README.md index b1ea5009..37dadcf1 100644 --- a/general/event/README.md +++ b/general/event/README.md @@ -8,28 +8,18 @@ products: - windows-wdk --- - - -<!--- - name: Hardware Event Sample - platform: WDM - language: cpp - category: General - description: Demonstrates different ways a kernel-mode driver can notify an application about a hardware event. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=617711 ----> - # Hardware Event Sample This sample demonstrates two different ways a Windows kernel-mode driver can notify an application about a hardware event. One way uses an event-based method, and the other uses an IRP-based method. Because the sample driver is not talking to any real hardware, it uses a timer DPC to simulate hardware events. The test application informs the driver whether it wants to be notified by signaling an event or by completing the pending IRP. Additionally, the test application specifies a relative time at which the DPC timer must fire. -*Event-based approach:* The application calls the [**CreateEvent**](http://msdn.microsoft.com/en-us/library/windows/hardware/ms682396) function to create an event. It then passes the event handle to the driver in an I/O control request that uses a private IOCTL code, IOCTL\_REGISTER\_EVENT. Because the driver is a monolithic, top-level driver, its IRP dispatch routines run in the application process context and, as a result, the event handle is still valid in the driver. The driver dereferences the user-mode handle into system space and saves the event object pointer for later use. Next, the driver queues a custom timer DPC. When the DPC fires, the driver signals the event by calling the [**KeSetEvent**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff553253) routine at DISPATCH\_LEVEL, and deletes the references to the event object. You can't use this approach if your driver is not a monolithic, top-level driver; that is because a driver can't guarantee the process context in a multi-level driver stack if the driver is not at the top of the stack. +*Event-based approach:* The application calls the [**CreateEvent**](https://docs.microsoft.com/windows/win32/api/synchapi/nf-synchapi-createeventa) function to create an event. It then passes the event handle to the driver in an I/O control request that uses a private IOCTL code, IOCTL\_REGISTER\_EVENT. Because the driver is a monolithic, top-level driver, its IRP dispatch routines run in the application process context and, as a result, the event handle is still valid in the driver. The driver dereferences the user-mode handle into system space and saves the event object pointer for later use. Next, the driver queues a custom timer DPC. When the DPC fires, the driver signals the event by calling the [**KeSetEvent**](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/wdm/nf-wdm-kesetevent) routine at DISPATCH\_LEVEL, and deletes the references to the event object. You can't use this approach if your driver is not a monolithic, top-level driver; that is because a driver can't guarantee the process context in a multi-level driver stack if the driver is not at the top of the stack. *Pending IRP-based approach:* The application makes a synchronous IOCTL\_REGISTER\_EVENT request. The driver sets the status of the device I/O control request to IRP pending, queues a timer DPC, and returns STATUS\_PENDING. When the timer fires to indicate a hardware event, the driver completes the pending IRP to notify the application about the hardware event. There are two advantages of IRP-based approach over the event-based approach. First, the driver can send a message to the application along with the event notification. Second, the driver routines don't have to run in the context of the process that made the request. Instead, the application can send a synchronous or asynchronous (overlapped) I/O control request to the driver. -**Note** This sample driver is not a Plug and Play driver. This is a minimal driver meant to demonstrate a feature of the operating system. Neither this driver nor its sample programs are intended for use in a production environment. Rather, they are intended for educational purposes and as a skeleton driver. +> [!NOTE] +> This sample driver is not a Plug and Play driver. This is a minimal driver meant to demonstrate a feature of the operating system. Neither this driver nor its sample programs are intended for use in a production environment. Rather, they are intended for educational purposes and as a skeleton driver. ## Run the sample diff --git a/general/filehistory/README.md b/general/filehistory/README.md index 5bda8a81..9cbadf3b 100644 --- a/general/filehistory/README.md +++ b/general/filehistory/README.md @@ -8,22 +8,11 @@ products: - windows-wdk --- - - -<!--- - name: File History Sample - platform: WDM - language: cpp - category: General - description: A console application that starts the file history service, if it is stopped, and schedules regular backups. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=617712 ----> - # File History Sample The FileHistory sample is a console application that starts the file history service, if it is stopped, and schedules regular backups. The application requires, as a command-line parameter, the path name of a storage device to use as the default backup target. -This sample application uses the [File History API](http://msdn.microsoft.com/en-us/library/windows/hardware/hh829789). The File History API enables third parties to automatically configure the File History feature on a Windows platform and customize it in accordance with their unique needs. +This sample application uses the [File History API](https://docs.microsoft.com/windows/win32/devnotes/file-history-api). The File History API enables third parties to automatically configure the File History feature on a Windows platform and customize it in accordance with their unique needs. ## Run the sample diff --git a/general/ioctl/kmdf/README.md b/general/ioctl/kmdf/README.md index 58a8a359..13afa81c 100644 --- a/general/ioctl/kmdf/README.md +++ b/general/ioctl/kmdf/README.md @@ -8,17 +8,6 @@ products: - windows-wdk --- - - -<!--- - name: Non-PnP Driver Sample - platform: KMDF - language: cpp - category: General WDF - description: Demonstrates how to write a non-PnP driver using the Kernel Mode Driver Framework. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=620307 ----> - # Non-PnP Driver Sample This sample is primarily meant to demonstrate how to write a NON-PNP driver using the Kernel Mode Driver Framework. @@ -43,23 +32,26 @@ This sample would be useful for writing a driver that does not interact with any The sample is accompanied by a simple multithreaded Win32 console application to test the driver. -*Disclaimer*: This is a minimal driver meant to demonstrate an OS feature. Neither it nor its sample programs are intended for use in a production environment. Rather, they are intended for educational purposes and as a skeleton driver. +> [!CAUTION] +> This is a minimal driver meant to demonstrate an OS feature. Neither it nor its sample programs are intended for use in a production environment. Rather, they are intended for educational purposes and as a skeleton driver. ## Build the sample -For information on how to build a driver solution using Microsoft Visual Studio, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). +For information on how to build a driver solution using Microsoft Visual Studio, see [Building a Driver with Visual Studio and the WDK](https://docs.microsoft.com/windows-hardware/drivers/develop/building-a-driver). If the build succeeds, you will find the driver, nonpnp.sys, and the test application, nonpnpapp.exe, in the binary output directory specified for the build environment. To test this driver, copy the nonpnp.inf into the same folder as the nonpnpapp.exe and the wdfcoinstaller\<version\>.dll . -**Note** You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. +> [!NOTE] +> You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](https://go.microsoft.com/fwlink/p/?LinkID=253170). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. Next, run nonpnpapp.exe, a simple Win32 multithreaded console mode application. The driver will be automatically loaded and started. When you exit the app, the driver will be stopped and removed. Usage: nonpnpapp.exe (-l) (-v version) -**Note** This application first tries to open the device (\\Device\\FileIo). If the device doesn't exist, it takes that as a hint that the driver is not loaded and tries to load the driver using service control manager API. If the service is loaded successfully, it tries to open the device again. If successful, it makes all four different types of DeviceControl calls to the driver. After that it makes a WriteFile call with an arbitrary size buffer. The driver, in response, writes that buffer to a file opened in the Create request. The name of the file was provided by the application as part of the device name and the directory path is hardcoded to %WINDIR%\\temp. When the WriteFile returns, the application makes a ReadFile call to read the file through the driver, and then compares the data returned by the driver with the one it originally wrote. If you specify -l option in command line, the application does this Write and Read operation in an infinite loop. The -v command line option is used to specify the version of the KMDF coinstaller (wdfcoinstaller\<version\>.dll) to load. If none is specified then it loads the coinstaller for v1.0 (wdfcoinstaller01000.dll) +> [!NOTE] +> This application first tries to open the device (\\Device\\FileIo). If the device doesn't exist, it takes that as a hint that the driver is not loaded and tries to load the driver using service control manager API. If the service is loaded successfully, it tries to open the device again. If successful, it makes all four different types of DeviceControl calls to the driver. After that it makes a WriteFile call with an arbitrary size buffer. The driver, in response, writes that buffer to a file opened in the Create request. The name of the file was provided by the application as part of the device name and the directory path is hardcoded to %WINDIR%\\temp. When the WriteFile returns, the application makes a ReadFile call to read the file through the driver, and then compares the data returned by the driver with the one it originally wrote. If you specify -l option in command line, the application does this Write and Read operation in an infinite loop. The -v command line option is used to specify the version of the KMDF coinstaller (wdfcoinstaller\<version\>.dll) to load. If none is specified then it loads the coinstaller for v1.0 (wdfcoinstaller01000.dll) ### WDF SECTION diff --git a/general/ioctl/wdm/README.md b/general/ioctl/wdm/README.md index a1ccad83..564887ef 100644 --- a/general/ioctl/wdm/README.md +++ b/general/ioctl/wdm/README.md @@ -8,17 +8,6 @@ products: - windows-wdk --- - - -<!--- - name: IOCTL - platform: WDM - language: cpp - category: General - description: Demonstrates usage of four different types of IOCTLs - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=617715 ----> - # IOCTL This sample demonstrates the usage of four different types of IOCTLs (METHOD\_IN\_DIRECT, METHOD\_OUT\_DIRECT, METHOD\_NEITHER, and METHOD\_BUFFERED). @@ -27,8 +16,9 @@ The sample shows how the user input and output buffers specified in the **Device The sample consists of a legacy device driver and a Win32 console test application. The test application opens a handle to the device exposed by the driver and makes all four different **DeviceIoControl** calls, one after another. To understand how the IRP fields are set the I/O manager, you should run the checked build version of the driver and look at the debug output. -**Note** This sample driver is not a Plug and Play driver. This is a minimal driver meant to demonstrate a feature of the operating system. Neither this driver nor its sample programs are intended for use in a production environment. Instead, they are intended for educational purposes and as a skeleton driver. +> [!CAUTION] +> This sample driver is not a Plug and Play driver. This is a minimal driver meant to demonstrate a feature of the operating system. Neither this driver nor its sample programs are intended for use in a production environment. Instead, they are intended for educational purposes and as a skeleton driver. -# Run the sample +## Run the sample To test this driver, copy the test app, Ioctlapp.exe, and the driver to the same directory, and run the application. The application will automatically load the driver, if it's not already loaded, and interact with the driver. When you exit the application, the driver will be stopped, unloaded and removed. diff --git a/general/obcallback/README.md b/general/obcallback/README.md index 782c7127..993b78d6 100644 --- a/general/obcallback/README.md +++ b/general/obcallback/README.md @@ -8,28 +8,17 @@ products: - windows-wdk --- - - -<!--- - name: ObCallback Callback Registration Driver - platform: WDM - language: cpp - category: General - description: Demonstrates the use of registered callbacks for process protection. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=617716 ----> - # ObCallback Callback Registration Driver The ObCallback sample driver demonstrates the use of registered callbacks for process protection. The driver registers control callbacks which are called at process creation. ## Design and Operation -The sample exercises both the [**PsSetCreateProcessNotifyRoutineEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff559951) and the [**ObRegisterCallbacks**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff558692) routines. The first example uses the **ObRegisterCallbacks** routine and a callback to restrict requested access rights during a open process action. The second example uses the **PsSetCreateProcessNotifyRoutineEx** routine to reject a process creation by examining the command line. +The sample exercises both the [**PsSetCreateProcessNotifyRoutineEx**](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/ntddk/nf-ntddk-pssetcreateprocessnotifyroutine) and the [**ObRegisterCallbacks**](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/wdm/nf-wdm-obregistercallbacks) routines. The first example uses the **ObRegisterCallbacks** routine and a callback to restrict requested access rights during a open process action. The second example uses the **PsSetCreateProcessNotifyRoutineEx** routine to reject a process creation by examining the command line. The following is a command line usage scenario to exercise access restriction: -``` +```cmd C:\> obcallbacktestctrl.exe -? (for command line help) C:\> obcallbacktestctrl.exe -install (installs the kernel driver) C:\> obcallbacktestctrl.exe -name notepad (specifies that the string "notepad" will be watched as a protected executable) @@ -49,7 +38,7 @@ C:\> obcallbacktestctrl.exe -uninstall (uninstall the kernel drive The following is another sample test you can run to prevent a process from being created: -``` +```cmd C:\> obcallbacktestctrl.exe -install (installs the kernel driver) C:\> obcallbacktestctrl.exe -reject notepad (specifies that the string "notepad" will be watched and prevented from starting as a process) diff --git a/general/pcidrv/README.md b/general/pcidrv/README.md index 245bfab3..877aa103 100644 --- a/general/pcidrv/README.md +++ b/general/pcidrv/README.md @@ -8,17 +8,6 @@ products: - windows-wdk --- - - -<!--- - name: PCIDRV - WDF Driver for PCI Device - platform: KMDF - language: cpp - category: General PCI WDF - description: Demonstrates how to write a KMDF driver for a PCI device. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=617717 ----> - # PCIDRV - WDF Driver for PCI Device This sample demonstrates how to write a KMDF driver for a PCI device. The sample works with the Intel 82557/82558 based PCI Ethernet Adapter (10/100) and Intel compatibles. @@ -53,7 +42,8 @@ The following is a list of key KMDF interfaces demonstrated in this sample: - Reading & Writing to the registry -Note: This sample provides an example of a minimal driver intended for educational purposes. Neither the driver nor its sample test programs are intended for use in a production environment. +> [!NOTE] +> This sample provides an example of a minimal driver intended for educational purposes. Neither the driver nor its sample test programs are intended for use in a production environment. As stated earlier, this sample is meant to demonstrate how to write a KMDF driver for a generic PCI device and not for PCI network controllers. For network controllers, you should write a monolithic NDIS miniport driver based on the samples given under the \\network\\ndis directory. @@ -61,21 +51,21 @@ Note that it is still possible to use a subset of KMDF APIs when writing a NDIS The sample driver has been tested on the following Intel Ethernet controllers: -Device Description | Hardware ID --------------------|------------ -IBM Netfinity 10/100 Ethernet Adapter | PCIVEN_8086&DEV_1229&SUBSYS_005C1014&REV_05 -Intel(R) PRO/100+ Management Adapter with Alert On LAN | PCI\VEN_8086&DEV_1229&SUBSYS_000E8086&REV_08 -Intel 8255x-based PCI Ethernet Adapter (10/100) | PCI\VEN_8086&DEV_1229&SUBSYS_00000000&REV_01 -Intel Pro/100 S Server Adapter | PCI\VEN_8086&DEV_1229&SUBSYS_00508086&REV_0D -Intel 8255x-based PCI Ethernet Adapter (10/100) | PCI\VEN_8086&DEV_1229&SUBSYS_00031179&REV_08 -Intel(R) PRO/100 VE Network Connection | PCI\VEN_8086&DEV_103D&SUBSYS_00011179&REV_83 -Intel(R) PRO/100 VM Network Connection | PCI\VEN_8086&DEV_1031&REV_42 -Intel(R) PRO/100 VE Network Connection | PCI\VEN_8086&DEV_1038&REV_41 -Intel(R) PRO/100 SR Mobile Adapter | PCI\VEN_8086&DEV_1229 +| Device Description | Hardware ID | +| --- | --- | +| IBM Netfinity 10/100 Ethernet Adapter | PCIVEN_8086&DEV_1229&SUBSYS_005C1014&REV_05 | +| Intel(R) PRO/100+ Management Adapter with Alert On LAN | PCI\VEN_8086&DEV_1229&SUBSYS_000E8086&REV_08 | +| Intel 8255x-based PCI Ethernet Adapter (10/100) | PCI\VEN_8086&DEV_1229&SUBSYS_00000000&REV_01 | +| Intel Pro/100 S Server Adapter | PCI\VEN_8086&DEV_1229&SUBSYS_00508086&REV_0D | +| Intel 8255x-based PCI Ethernet Adapter (10/100) | PCI\VEN_8086&DEV_1229&SUBSYS_00031179&REV_08 | +| Intel(R) PRO/100 VE Network Connection | PCI\VEN_8086&DEV_103D&SUBSYS_00011179&REV_83 | +| Intel(R) PRO/100 VM Network Connection | PCI\VEN_8086&DEV_1031&REV_42 | +| Intel(R) PRO/100 VE Network Connection | PCI\VEN_8086&DEV_1038&REV_41 | +| Intel(R) PRO/100 SR Mobile Adapter | PCI\VEN_8086&DEV_1229 | ## Using this sample as a standalone driver -``` +```txt --------------------- | | | MYPING | <-- Usermode test application @@ -105,13 +95,13 @@ You can install the driver as a standalone driver of a custom setup class, calle The PCIDRV sample acts as a power policy owner of the device and implements all the wait-wake and idle detection logic. -## INSTALLATION +## Installation The driver can be installed as a Net class driver or as a standalone driver (user defined class). The KMDF versions of the INF files are dynamically generated from .INX file. In addition to the driver files, you have to include the WDF coinstaller DLL from the \\redist\\wdf folder of the WDK. -You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](http://go.microsoft.com/fwlink/p/?LinkID=226396). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. +You can obtain redistributable framework updates by downloading the *wdfcoinstaller.msi* package from [WDK 8 Redistributable Components](https://go.microsoft.com/fwlink/p/?LinkID=253170). This package performs a silent install into the directory of your Windows Driver Kit (WDK) installation. You will see no confirmation that the installation has completed. You can verify that the redistributables have been installed on top of the WDK by ensuring there is a redist\\wdf directory under the root directory of the WDK, %ProgramFiles(x86)%\\Windows Kits\\8.0. -### TESTING +### Testing To test standalone driver configuration: You should use the specially developed ping application, called MYPING that comes with the sample. The Ping.exe provided in the system will not work because in this configuration, the test card is not bound to any network protocol - it's not seen as Net device by the system. Currently the test application doesn't have ability to get an IP address from a network DHCP server. As a result, it is better to connect the network device to a private hub and ping another machine connected to that hub. For example, let us say you have a test machine A and another machine B (development box). @@ -157,18 +147,19 @@ Other menu options of myping applications are: - Exit: Terminate the application. -**Note** You can use this application only on a device installed in the standalone configuration. If you run it on a device that's installed as a miniport, you will get an error message. For such devices, you can use the system provided ping.exe. +> [!NOTE] +> You can use this application only on a device installed in the standalone configuration. If you run it on a device that's installed as a miniport, you will get an error message. For such devices, you can use the system provided ping.exe. -## RESOURCES +## Resources For the latest release of the Windows Driver Kit, see [Download the Windows Driver Kit (WDK)](https://docs.microsoft.com/windows-hardware/drivers/download-the-wdk). If you have questions on using or adapting this sample for your project, you can either contact Microsoft Technical Support or post your questions in the Microsoft driver development newsgroup. -## FILE MANIFEST +## File manifest -File | Description ------|------------ -KMDF | Contains the driver. -KMDF\HW | Contains hardware specific code. -TEST | Contains source of test application (MYPING). +| File | Description | +| --- | --- | +| KMDF | Contains the driver | +| KMDF\HW | Contains hardware specific code | +| TEST | Contains source of test application (MYPING) | |