diff options
Diffstat (limited to 'network/ndis')
| -rw-r--r-- | network/ndis/extension/README.md | 13 | ||||
| -rw-r--r-- | network/ndis/filter/README.md | 126 | ||||
| -rw-r--r-- | network/ndis/mux/README.md | 109 | ||||
| -rw-r--r-- | network/ndis/netvmini/6x/README.md | 13 |
4 files changed, 136 insertions, 125 deletions
diff --git a/network/ndis/extension/README.md b/network/ndis/extension/README.md index 690a5efb..c6965595 100644 --- a/network/ndis/extension/README.md +++ b/network/ndis/extension/README.md @@ -8,17 +8,6 @@ products: - windows-wdk --- - - -<!--- - name: Hyper-V Extensible Switch extension filter driver - platform: WDM - language: cpp - category: Network - description: A base library used to implement a Hyper-V Extensible Switch extension filter driver. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=617913 ----> - # Hyper-V Extensible Switch extension filter driver This sample contains a base library used to implement a Hyper-V Extensible Switch extension filter driver. This sample also contains two different extension filter drivers that were developed by using the library. @@ -35,4 +24,4 @@ MsForwardExt is a basic forwarding extension filter driver that is implemented b Use the *install.cmd* script provided with each extension filter driver. The *install.cmd* uses **netcfg** to install the extension and **mofcomp** to register any required mof files. The PowerShell cmdlet *Enable-VmSwitchExtension* can then be used to enable the extension filter driver on a Hyper-V Extensible Switch. -For more information on Hyper-V Extensible Switch extensions, see [Hyper-V Extensible Switch](http://msdn.microsoft.com/en-us/library/windows/hardware/hh598161). +For more information on Hyper-V Extensible Switch extensions, see [Hyper-V Extensible Switch](https://docs.microsoft.com/windows-hardware/drivers/network/hyper-v-extensible-switch). diff --git a/network/ndis/filter/README.md b/network/ndis/filter/README.md index a7093842..c9615ce2 100644 --- a/network/ndis/filter/README.md +++ b/network/ndis/filter/README.md @@ -10,53 +10,68 @@ products: # NDIS 6.0 Filter Driver -The Ndislwf sample is a do-nothing pass-through NDIS 6 filter driver that demonstrates the basic principles underlying an NDIS 6.0 Filter driver. The sample replaces the NDIS 5 Sample Intermediate Driver (Passthru driver). +The Ndislwf sample is a do-nothing pass-through NDIS 6 filter driver that demonstrates the basic principles underlying an NDIS 6.0 Filter driver. The sample replaces the NDIS 5 Sample Intermediate Driver (Passthrough driver). Although this sample filter driver is installed as a modifying filter driver, it doesn't modify any packets; it only repackages and sends down all OID requests. You can modify this filter driver to change packets before passing them along. Or you can use the filter to originate new packets to send or receive. For example, the filter could encrypt/compress outgoing and decrypt/decompress incoming data. -For more information, see [NDIS Filter Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565492) in the network devices design guide. +For more information, see [NDIS Filter Drivers](https://docs.microsoft.com/windows-hardware/drivers/network/ndis-filter-drivers) in the network devices design guide. +## Automatic deployment -Automatic deployment --------------------- +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Provision a computer for driver deployment and testing](https://docs.microsoft.com/windows-hardware/drivers/gettingstarted/provision-a-target-computer-wdk-8-1). -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). After you have provisioned the target computer, continue with these steps: +After you have provisioned the target computer, continue with these steps: -1. On the host computer, in **Visual Studio**, in **Solution Explorer**, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -2. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. -3. On the **Build** menu, choose **Build Solution**. -4. On the target computer, open **Control Panel**. Click **Network and Internet** and then open **Network and Sharing Center**. -5. Under **View your active networks**, click the connection listed under **Connections:** and click **Properties**. If you have previously installed this sample, highlight it in the list. -6. Click **Install**, then **Service**, then **Add**. - **Note** You may see multiple instances of the **NDIS Sample LightWeight Filter** service. If so, highlight the newest one. -7. Click **Have Disk**. -8. In the **Install from Disk** dialog, browse to the DriverTest\\Drivers directory. Highlight the netlwf.inf file and click **Open**, then click OK. This should show **NDIS Sample LightWeight Filter** in a list of **Network Services**. Highlight **NDIS Sample LightWeight Filter** and click **OK**. Click **OK**. Click **Close**. Click **Close**. This installs the Ndislwf filter driver service. +1. On the host computer, in **Visual Studio**, in **Solution Explorer**, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. -**Note** If you've installed the Ndislwf sample on the target computer before, you can use the [PnPUtil](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550419) tool to delete the older versions from the driver store. +1. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Do not install**. Click **OK**. -Manual deployment ------------------ +1. On the **Build** menu, choose **Build Solution**. -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](https://docs.microsoft.com/en-us/windows-hardware/drivers/develop/preparing-a-computer-for-manual-driver-deployment). +1. On the target computer, open **Control Panel**. Click **Network and Internet** and then open **Network and Sharing Center**. + +1. Under **View your active networks**, click the connection listed under **Connections:** and click **Properties**. If you have previously installed this sample, highlight it in the list. + +1. Click **Install**, then **Service**, then **Add**. + + > [!NOTE] + > You may see multiple instances of the **NDIS Sample LightWeight Filter** service. If so, highlight the newest one. + +1. Click **Have Disk**. + +1. In the **Install from Disk** dialog, browse to the DriverTest\\Drivers directory. Highlight the netlwf.inf file and click **Open**, then click OK. This should show **NDIS Sample LightWeight Filter** in a list of **Network Services**. Highlight **NDIS Sample LightWeight Filter** and click **OK**. Click **OK**. Click **Close**. Click **Close**. This installs the Ndislwf filter driver service. + +> [!NOTE] +> If you've installed the Ndislwf sample on the target computer before, you can use the [PnPUtil](https://docs.microsoft.com/windows-hardware/drivers/devtest/pnputil) tool to delete the older versions from the driver store. + +## Manual deployment + +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](https://docs.microsoft.com/windows-hardware/drivers/devtest/devcon) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](https://docs.microsoft.com/windows-hardware/drivers/develop/preparing-a-computer-for-manual-driver-deployment). Ndislwf is installed as a service (called **NDIS Sample LightWeight Filter** in the supplied INF). To install it, do the following: -1. Prepare an installation directory on the target computer and copy these files from the host computer into the directory: -``` - netlwf.cat - netlwf.inf - ndislwf.sys -``` -2. Open **Control Panel**. -3. Click **Network and Internet** and then open **Network and Sharing Center**. Under **View your active networks**, click the connection listed under **Connections**: and click **Properties**. -4. If you have previously installed this sample, highlight it in the list. -5. Click **Install**, then **Service**, then **Add**, then **Have Disk**. -6. Browse to the installation directory. Highlight the netlwf.inf file and click **Open**, then click OK. This should show **NDIS Sample LightWeight Filter** in a list of Network Services. Highlight this and click OK. Click OK. This installs the Ndislwf filter driver. +1. Prepare an installation directory on the target computer and copy these files from the host computer into the directory: + + - netlwf.cat + + - netlwf.inf + + - ndislwf.sys + +1. Open **Control Panel**. -**Note** If you've installed the Ndislwf sample on the target computer before, you can use the [PnPUtil](http://msdn.microsoft.com/en-us/library/windows/hardware/ff550419) tool to delete the older versions from the driver store. +1. Click **Network and Internet** and then open **Network and Sharing Center**. Under **View your active networks**, click the connection listed under **Connections**: and click **Properties**. -Viewing sample output in the debugger -------------------------------------- +1. If you have previously installed this sample, highlight it in the list. + +1. Click **Install**, then **Service**, then **Add**, then **Have Disk**. + +1. Browse to the installation directory. Highlight the netlwf.inf file and click **Open**, then click OK. This should show **NDIS Sample LightWeight Filter** in a list of Network Services. Highlight this and click OK. Click OK. This installs the Ndislwf filter driver. + +> [!NOTE] +> If you've installed the Ndislwf sample on the target computer before, you can use the [PnPUtil](https://docs.microsoft.com/windows-hardware/drivers/devtest/pnputil) tool to delete the older versions from the driver store. + +## Viewing sample output in the debugger ### Setting up kernel-mode debugging automatically @@ -64,32 +79,32 @@ If you chose to deploy your driver automatically, then kernel debugging is alrea On the host computer, in **Visual Studio**, in the **Debug** menu, choose **Attach to Process**. For **Transport**, choose **Windows Kernel Mode Debugger**. For **Qualifier**, choose the name of your target computer. Click **Attach**. -**Note** If you see a dialog box that asks you to allow the debugger to communicate through the firewall, click the boxes for all types of networks. Click **Allow Access**. +> [!NOTE] +> If you see a dialog box that asks you to allow the debugger to communicate through the firewall, click the boxes for all types of networks. Click **Allow Access**. -For more information, see [Setting Up Kernel-Mode Debugging in Visual Studio](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439376). +For more information, see [Setting Up Kernel-Mode Debugging in Visual Studio](http://msdn.microsoft.com/library/windows/hardware/hh439376). ### Setting up kernel-mode debugging manually -If you chose to deploy your driver manually, then you need to set up kernel debugging manually. For instructions, see [Setting Up Kernel-Mode Debugging Manually](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439378). +If you chose to deploy your driver manually, then you need to set up kernel debugging manually. For instructions, see [Setting Up Kernel-Mode Debugging Manually](https://docs.microsoft.com/windows-hardware/drivers/debugger/setting-up-kernel-mode-debugging-in-visual-studio). The kernel-mode debuggers (WinDbg.exe and Kd.exe) are included in the WDK. -On the host computer, locate and open a kernel-mode debugger (example: c:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\windbg.exe). Establish a kernel-mode debugging session between the host and target computers. The details of how to do this depend on the type of debug cable you are using. For information about how to start a debugging session, see [Setting Up Kernel-Mode Debugging Manually](http://msdn.microsoft.com/en-us/library/windows/hardware/hh439378). +On the host computer, locate and open a kernel-mode debugger (example: c:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\windbg.exe). Establish a kernel-mode debugging session between the host and target computers. The details of how to do this depend on the type of debug cable you are using. For information about how to start a debugging session, see [Setting Up Kernel-Mode Debugging Manually](https://docs.microsoft.com/windows-hardware/drivers/debugger/setting-up-a-network-debugging-connection). -Setting kd\_default\_mask -------------------------- +## Setting kd\_default\_mask -This sample calls [**DbgPrint**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff543632) to send trace messages to the kernel-mode debugger. To see the trace messages, you must set the value of the **kd\_default\_mask** variable. +This sample calls [**DbgPrint**](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/wdm/nf-wdm-dbgprint) to send trace messages to the kernel-mode debugger. To see the trace messages, you must set the value of the **kd\_default\_mask** variable. On the host computer, break in to the debugger if you are not already broken in. (In the **Debug** menu, choose **Break** or **Break All**, or press **CTRL-Break**). At the debugger command line, enter this command: **ed kd\_default\_mask 0x8**. To resume execution of the target computer, enter the **g** command in the debugger. (In the **Debug** menu, choose **Continue**.) -Viewing trace messages ----------------------- +## Viewing trace messages On the host computer, in the kernel-mode debugger, verify that you see trace messages similar to these: -``` + +```txt NDISLWF: ===>DriverEntry... NDISLWF: ===>FilterRegisterOptions NDISLWF: <===FilterRegisterOptions @@ -99,14 +114,21 @@ NDISLWF: <===DriverEntry, Status = 0 NDISLWF: ===>FilterAttach: NdisFilterHandle FFFFE00000F73650 NDISLWF: <===FilterAttach: Status 0 ``` -What the Ndislwf sample driver does: ------------------------------------- -1. During [*DriverEntry*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544113), the ndislwf driver registers as an NDIS 6 filter driver. -2. Later on, NDIS calls Ndislwf's [*FilterAttach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549905) handler, for each underlying NDIS adapter on which it is configured to attach. -3. In the context of [*FilterAttach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549905) Handler, the filter driver calls [**NdisFSetAttributes**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff562619) to register its filter module context with NDIS. After that, the filter driver can read its own setting in registry by calling [**NdisOpenConfigurationEx**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff563717), and call other `NdisXxx` functions. -4. After [*FilterAttach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549905) successfully returns, NDIS restarts the filter later by calling its [*FilterRestart*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549962) handler. *FilterRestart* should prepare to handle send/receive data. After restart return successfully, filter driver should be able to process send/receive. -5. All requests and sends coming from overlying drivers for the Ndislwf filter driver are repackaged if necessary and sent down to NDIS, to be passed to the underlying NDIS driver. -6. All indications arriving from an underlying NDIS driver are forwarded up by Ndislwf filter driver. -7. NDIS calls the filter's [*FilterPause*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549957) handler when NDIS needs to detach the filter from the stack or there is some configuration changes in the stack. In processing the pause request from NDIS, the Ndislwf driver waits for all its own outstanding requests to be completed before it completes the pause request. -8. NDIS calls the Ndislwf driver's [*FilterDetach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549918) entry point when NDIS needs to detach a filter module from NDIS stack. The *FilterDetach* handler should free all the memory allocation done in [*FilterAttach*](http://msdn.microsoft.com/en-us/library/windows/hardware/ff549905), and undo the operations it did in *FilterAttach* Handler. +## What the Ndislwf sample driver does + +1. During [*DriverEntry*](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/wdm/nc-wdm-driver_initialize), the ndislwf driver registers as an NDIS 6 filter driver. + +1. Later on, NDIS calls Ndislwf's [*FilterAttach*](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/ndis/nc-ndis-filter_attach) handler, for each underlying NDIS adapter on which it is configured to attach. + +1. In the context of [*FilterAttach*](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/ndis/nc-ndis-filter_attach) Handler, the filter driver calls [**NdisFSetAttributes**](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/ndis/nf-ndis-ndisfsetattributes) to register its filter module context with NDIS. After that, the filter driver can read its own setting in registry by calling [**NdisOpenConfigurationEx**](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/ndis/nf-ndis-ndisopenconfigurationex), and call other `NdisXxx` functions. + +1. After [*FilterAttach*](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/ndis/nc-ndis-filter_attach) successfully returns, NDIS restarts the filter later by calling its [*FilterRestart*](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/ndis/nc-ndis-filter_restart) handler. *FilterRestart* should prepare to handle send/receive data. After restart return successfully, filter driver should be able to process send/receive. + +1. All requests and sends coming from overlying drivers for the Ndislwf filter driver are repackaged if necessary and sent down to NDIS, to be passed to the underlying NDIS driver. + +1. All indications arriving from an underlying NDIS driver are forwarded up by Ndislwf filter driver. + +1. NDIS calls the filter's [*FilterPause*](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/ndis/nc-ndis-filter_pause) handler when NDIS needs to detach the filter from the stack or there is some configuration changes in the stack. In processing the pause request from NDIS, the Ndislwf driver waits for all its own outstanding requests to be completed before it completes the pause request. + +1. NDIS calls the Ndislwf driver's [*FilterDetach*](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/ndis/nc-ndis-filter_detach) entry point when NDIS needs to detach a filter module from NDIS stack. The *FilterDetach* handler should free all the memory allocation done in [*FilterAttach*](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/ndis/nc-ndis-filter_attach), and undo the operations it did in *FilterAttach* Handler. diff --git a/network/ndis/mux/README.md b/network/ndis/mux/README.md index 681158f0..bfe83318 100644 --- a/network/ndis/mux/README.md +++ b/network/ndis/mux/README.md @@ -12,7 +12,7 @@ products: The MUX Intermediate Miniport (IM) driver is an NDIS 6.0 driver that demonstrates the operation of an "N:1" MUX driver.The sample demonstrates creating multiple virtual network devices on top of a single lower adapter. Protocols bind to these virtual adapters as if they are real adapters. Examples of Intermediate Miniport drivers that can use this framework are Virtual LAN (VLAN) drivers. Included in the project is a sample Notify Object that demonstrates how to write a notify object for installing and configuring an NDIS MUX intermediate miniport (IM) driver that implements an N:1 relationship between upper and lower bindings, for example, it creates multiple virtual network devices on top of a single lower adapter. Protocols bind to these virtual adapters as if they are real adapters. Examples of Intermediate Miniport drivers that can use this type of notify object are Virtual LAN (VLAN) drivers. -For more information, see [NDIS Intermediate Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565773) in the network devices design guide. +For more information, see [NDIS Intermediate Drivers](https://docs.microsoft.com/windows-hardware/drivers/network/ndis-intermediate-drivers) in the network devices design guide. ## Installing the sample @@ -20,17 +20,21 @@ MUX is installed as a protocol (called *Sample Mux-IM Protocol Driver* in the su To install, follow the steps below: -1. Prepare an installation directory that contains these files: muxp.inf, mux\_mp.inf, mux.sys and mux.dll (notification object DLL, built in this DDK at network\\ndis\\mux\\notifyob). -2. On the desktop, right-click the **My Network Places** icon and choose **Properties**. -3. Right-click on the relevant **Local Area Connection** icon and choose **Properties**. -4. Click **Install**, then **Protocol**, then **Add**, then **Have Disk**. -5. Browse to the drive/directory containing the files listed above. Click **OK**. This should show **Sample Mux-IM Protocol Driver** in a list of Network Protocols. Highlight this and click **OK**. This should install the MUX driver. -6. Click **OK** or **Yes** each time the system prompts with a warning regarding installation of unsigned files. This is necessary because binaries generated via the DDK build environment are not signed. +1. Prepare an installation directory that contains these files: muxp.inf, mux\_mp.inf, mux.sys and mux.dll (notification object DLL, built in this DDK at network\\ndis\\mux\\notifyob). + +1. On the desktop, right-click the **My Network Places** icon and choose **Properties**. + +1. Right-click on the relevant **Local Area Connection** icon and choose **Properties**. + +1. Click **Install**, then **Protocol**, then **Add**, then **Have Disk**. + +1. Browse to the drive/directory containing the files listed above. Click **OK**. This should show **Sample Mux-IM Protocol Driver** in a list of Network Protocols. Highlight this and click **OK**. This should install the MUX driver. + +1. Click **OK** or **Yes** each time the system prompts with a warning regarding installation of unsigned files. This is necessary because binaries generated via the DDK build environment are not signed. Two .INF files are needed rather than one because MUX is installed both as a protocol and a miniport. -NDIS MUX Intermediate Driver ----------------------------- +## NDIS MUX Intermediate Driver The driver binds to Ethernet (NdisMedium802\_3) adapters as a protocol, and exposes one or more virtual Ethernet devices over each lower adapter, based on its configuration. The term "VELAN" is used to denote a Virtual Ethernet LAN adapter implemented by this driver. @@ -58,13 +62,13 @@ The VLAN ID for each VELAN (virtual miniport) can be configured as follows. Righ When it loads, i.e. from its DriverEntry function, the MUX driver registers as an Intermediate miniport driver and as a protocol, in that order. -### Binding and VELAN Creation +#### Binding and VELAN Creation NDIS calls MUX's BindAdapter function, `PtBindAdapter`, for each underlying NDIS adapter to which it is configured to bind. This function allocates an `ADAPT` structure to represent the lower adapter, and calls `NdisOpenAdapter` to set up a binding to it. In the context of `BindAdapterHandler`, after successfully opening a binding to the underlying adapter, the driver queries the reserved keyword "UpperBindings" to get a list of device names for the virtual adapters that this particular binding is to expose, see `PtBootStrapVElans` for more details. Note that the MUX driver does not create bindings (for example, call `NdisOpenAdapter`) from any context other than its BindAdapter function. This is recommended behavior for all drivers of this type. For each device name specified in the "UpperBindings" key, the MUX driver allocates a VELAN data structure to represent the virtual miniport, calls `NdisIMInitializeDeviceInstanceEx`. In response, NDIS eventually calls the MUX miniport's MiniportInitialize entry point, MPInitialize, for each VELAN. After MPInitialize successfully returns, NDIS takes care of getting upper-layer protocols to bind to the newly created virtual adapter(s). -### Unbinding and Halting +#### Unbinding and Halting NDIS calls MUX's `UnbindAdapter` handler, `PtUnbindAdapter`, to request it to unbind from a lower adapter. In processing this, MUX calls `NdisIMDeInitializeDeviceInstance` for each VELAN instantiated on the indicated adapter, see `PtStopVElan` for details. This call results in NDIS first unbinding any protocols bound to the indicated VELAN, and then calling the MiniportHalt routine, `MPHalt`, for that VELAN. `MPHalt` waits for any outstanding receives/sends on the VELAN to finish before unlinking the VELAN from the ADAPT. @@ -72,11 +76,11 @@ NDIS calls MUX's `UnbindAdapter` handler, `PtUnbindAdapter`, to request it to un `MPHalt` may also be called if the VELAN device is disabled, e.g. from the Network Connections Folder. There is no special code within `MPHalt` to handle this condition. However, `PtUnbindAdapter` takes care to not attempt to deinitialize a VELAN miniport (via `NdisIMDeInitializeDeviceInstance`) that has already been halted. -### Handling Queries +#### Handling Queries `MPRequest` is the MUX driver's function that handles queries for OID values on VELAN miniports. Most of the "Ethernet" type information for the virtual miniport is stored in the VELAN structure itself, and the driver returns information from this structure. The queries that are forwarded are **OID\_GEN\_MEDIA\_CONNECT\_STATUS**, **OID\_PNP\_CAPABILITIES** and **OID\_PNP\_WAKE\_UP\_PATTERN\_LIST**. See "Handling Power Management" below for more information about the latter two OIDs. -### Handling Sets +#### Handling Sets `MPRequest` handles setting OID values on VELAN miniports. Data management OIDs handled by the MUX driver are **OID\_802\_3\_MULTICAST\_LIST** and **OID\_GEN\_CURRENT\_PACKET\_FILTER**. The multicast list is handled entirely within the MUX driver, it just stores the set of multicast addresses in the VELAN structure, for reference during receive-side data processing. The packet filter is handled in a different way. The MUX driver combines the packet filter settings (bitwise OR) of all VELANs associated with the same lower adapter. If the combined packet filter is non-zero, MUX sends a Set request with a value of **NDIS\_PACKET\_TYPE\_PROMISCUOUS** for **OID\_GEN\_CURRENT\_PACKET\_FILTER** to start receives on the lower adapter. If the combined packet filter is zero, MUX sets the lower adapter's packet filter to 0 (turns off all receives if there aren't any interested protocols). @@ -84,13 +88,13 @@ Note that setting the lower adapter to promiscuous mode is only done here in ord Some power management OIDs are forwarded to the lower miniport. See "Handling Power Management" below for details. -### Sending Data +#### Sending Data Data sent down on a VELAN miniport is forwarded to the lower adapter. The MUX driver itself does not generate any data of its own. The MUX driver clones a `NET_BUFFER_LIST` for each `NetBufferList` passed to its `MPSendNetBufferLists` function, and saves a pointer to the original `NET_BUFFER_LIST` in the reserved area of the `NET_BUFFER_LIST` structure. When the lower adapter completes the send (`PtSendNBLComplete`), MUX picks up the original packet and calls `NdisMSendNetBufferListsComplete` to complete the original send request. If a non-zero VLAN ID is configured for the VELAN, and/or the packet has non-zero Ieee8021QInfo per-packet information, then the MUX driver inserts an NDIS buffer containing a tag header to the front of the packet before sending it down, see function `MPHandleSendTagging` for details. -### Receiving Data +#### Receiving Data Data received from a lower adapter is indicated up on zero or more VELANs. The `PtReceiveNBL` function is called for each `NetBufferList` received from the lower adapter. The received data is checked for matches with the packet filter and multicast list for each VELAN associated with the adapter (see `PtMatchPacketToVElan`). Whenever a match is found, a new `NET_BUFFER_LIST` is allocated and set to point to the received data. A pointer to the original received `NET_BUFFER_LIST` (if any) is also stored in the new `NET_BUFFER_LIST`'s reserved area. This packet is indicated up via `NdisMIndicateReceiveNetBufferLists` to all interested protocols on that VELAN. @@ -98,15 +102,15 @@ The driver's `MPReturnNetBufferLists` function is called either by NDIS or by MU The driver indicates up received frames that do not have an IEEE 802.1Q tag header in them, see function **PtHandleRcvTagging**. It always strips off tag headers, if present, on received frames. If a non-zero VLAN ID is configured, then it checks received frames that contain tag headers for matching VLAN Ids, only matching frames are indicated up to protocols. Any VLAN/priority information present in incoming frames is copied to per-packet information fields of indicated `NET_BUFFER_LIST` structures. -### Status Indications +#### Status Indications The only status indications that are forwarded up by MUX are media connect status indications. See `PtStatus` for more details. -### Handling Power Management +#### Handling Power Management During initialization (`MPInitialize`), the MUX miniport sets the attribute **NDIS\_ATTRIBUTE\_NO\_HALT\_ON\_SUSPEND** in its call to `NdisMSetMiniportAttributes`. When the MUX miniport is requested to report its Plug and Play capabilities (**OID\_PNP\_CAPABILITIES**), the MUX miniport forwards the request to the underlying miniport. If this request succeeds, then the MUX miniport overwrites the following fields before successfully completing the original request: -``` +```txt NDIS_DEVICE_POWER_STATE MinMagicPacketWakeUp = NdisDeviceStateUnspecified; NDIS_DEVICE_POWER_STATE MinPatternWakeUp= NdisDeviceStateUnspecified; NDIS_DEVICE_POWER_STATE MinLinkChangeWakeUp=NdisDeviceStateUnspecified @@ -120,42 +124,47 @@ NDIS calls the MUX driver's `ProtocolPnPEvent` function (`PtPNPHandler`) wheneve Queries/sets received on a VELAN miniport that are to be forwarded to the underlying adapter are queued on the VELAN if the underlying adapter is at a low power state. These are picked up for processing on receiving a notification that the underlying adapter is back to a powered-up state. -### Handling Global Reconfiguration +#### Handling Global Reconfiguration All modifications to VELAN configuration are accompanied by PnP reconfigure notifications, for example, `NetEventReconfigure` events passed to the MUX's `PnPEventHandler`, `PtPNPHandler`. This driver takes a broad approach to handling reconfiguration, which is to simply re-examine all the "UpperBindings" keys for all currently bound adapters, and start off VELANs for any that do not exit, see `PtBootStrapVElans` for details. -### Canceling Sends +#### Canceling Sends MUX propagates send cancellations from protocols above it to lower miniports. -Sample Notify Object --------------------- +## Sample Notify Object -### Preprocessor Flags: +### Preprocessor Flags -### DISABLE\_PROTOCOLS\_TO\_PHYSICAL +#### DISABLE\_PROTOCOLS\_TO\_PHYSICAL When this flag is defined in the Sources file, the notify object disables the bindings of other protocols such as TCP/IP to the physical adapters during the installation. When all the virtual adapters are removed either through the custom property page or as a result of uninstalling the MUX driver, the notify object re-enables those bindings. -### PASSTHRU\_NOTIFY +#### PASSTHRU\_NOTIFY This flag is defined to allow the MUX driver to be used in a passthru mode. When this flag is defined, the notify object: -1. Creates only one virtual miniport for every physical adapter the MUX protocol edge binds to. -2. Disables the property page to prevent adding of additional virtual miniports. -3. Stores the device name of the virtual adapter in REG\_SZ registry value under HKLM\\System\\CurrentControlSet\\Services\\muxp\\Parameters\\Adapters\\{PhysicalAdaptersInstanceGuid}\\UpperBindings, because there is one to one binding. In the MUX mode (when this flag is not defined), the notify object stores the device name in a REG\_MULTI\_SZ registry value as there could be more than one virtual miniports. +1. Creates only one virtual miniport for every physical adapter the MUX protocol edge binds to. + +1. Disables the property page to prevent adding of additional virtual miniports. + +1. Stores the device name of the virtual adapter in REG\_SZ registry value under HKLM\\System\\CurrentControlSet\\Services\\muxp\\Parameters\\Adapters\\{PhysicalAdaptersInstanceGuid}\\UpperBindings, because there is one to one binding. In the MUX mode (when this flag is not defined), the notify object stores the device name in a REG\_MULTI\_SZ registry value as there could be more than one virtual miniports. You can also use this notify object with the Passthru driver by doing the following: -1. Change the protocol name in file \\ndis\\passthru\\passthru.c from **PASSTHRU** to **MUXP.** -2. Change the driver name from Passthru to MUX in the sources file. -3. Rebuild the driver to obtain a mux.sys driver binary. -4. Build the MUX notify object with **PASSTHRU\_NOTIFY** defined. -5. Use the MUX inf files, muxp.inf and mux\_mp.inf, to install the driver and dll. +1. Change the protocol name in file \\ndis\\passthru\\passthru.c from **PASSTHRU** to **MUXP.** + +1. Change the driver name from Passthru to MUX in the sources file. + +1. Rebuild the driver to obtain a mux.sys driver binary. + +1. Build the MUX notify object with **PASSTHRU\_NOTIFY** defined. + +1. Use the MUX inf files, muxp.inf and mux\_mp.inf, to install the driver and dll. The benefit of using techniques in the MUX notify object for a 1:1 intermediate driver (e.g. Passthru) is to be able to exercise higher level of control over the bindings of MUX with other components in the system, which is not possible with the IM filter driver. -### CUSTOM\_EVENTS +#### CUSTOM\_EVENTS When this macro is defined, the notify object shows how to send custom events to the MUX IM driver when a virtual miniport is added or removed. @@ -163,9 +172,11 @@ When this macro is defined, the notify object shows how to send custom events to During installation, the notify object performs the following operations: -- It creates one virtual adapter for each physical adapter the MUX protocol edge binds to. -- It disables the bindings of other protocols such as TCP/IP to physical adapters if it has been compiled with DISABLE\_PROTOCOLS\_TO\_PHYSICAL defined in the Sources file. This is the most commonly desired behavior for N:1 MUX drivers. -- It disables the bindings of the protocol edge of the MUX IM driver with all its virtual adapters. +- It creates one virtual adapter for each physical adapter the MUX protocol edge binds to. + +- It disables the bindings of other protocols such as TCP/IP to physical adapters if it has been compiled with DISABLE\_PROTOCOLS\_TO\_PHYSICAL defined in the Sources file. This is the most commonly desired behavior for N:1 MUX drivers. + +- It disables the bindings of the protocol edge of the MUX IM driver with all its virtual adapters. The notify object provides a custom property page for the MUX IM driver. The custom property page allows the user to add one or more virtual adapters on top of a physical adapter or delete an existing virtual adapter. @@ -173,16 +184,16 @@ When the MUX IM driver is uninstalled, or binding is disabled, or the user delet ### File Manifest -File | Description ------|------------ -Miniport.c | Miniport related routines for the MUX driver -Mux.c | DriverEntry routine and any routines common to the MUX miniport and protocol -Mux.h | Prototypes of all functions and data structures used by the MUX driver -Mux.rc | Resource file for the MUX driver -Muxp.inf | Installation INF for the service (protocol side installation) -Mux_mp.inf | Installation INF for the miniport (virtual device installation) -Precomp.h | Precompile header file -Protocol.c | Protocol related routines for the MUX driver -Public.h | Contains the common declarations shared by driver and user applications +| File | Description | +| --- | --- | +| Miniport.c | Miniport related routines for the MUX driver | +| Mux.c | DriverEntry routine and any routines common to the MUX miniport and protocol | +| Mux.h | Prototypes of all functions and data structures used by the MUX driver | +| Mux.rc | Resource file for the MUX driver | +| Muxp.inf | Installation INF for the service (protocol side installation) | +| Mux_mp.inf | Installation INF for the miniport (virtual device installation) | +| Precomp.h | Precompile header file | +| Protocol.c | Protocol related routines for the MUX driver | +| Public.h | Contains the common declarations shared by driver and user applications | -For more information, see [NDIS Intermediate Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565773) in the network devices design guide. +For more information, see [NDIS Intermediate Drivers](https://docs.microsoft.com/windows-hardware/drivers/network/ndis-intermediate-drivers) in the network devices design guide. diff --git a/network/ndis/netvmini/6x/README.md b/network/ndis/netvmini/6x/README.md index 2accdad8..3ad33ac0 100644 --- a/network/ndis/netvmini/6x/README.md +++ b/network/ndis/netvmini/6x/README.md @@ -8,17 +8,6 @@ products: - windows-wdk --- - - -<!--- - name: NDIS Virtual Miniport Driver - platform: WDM - language: cpp - category: Network - description: Demonstrates the functionality of an NDIS miniport driver without requiring a physical network adapter. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=617918 ----> - # NDIS Virtual Miniport Driver The NDIS Virtual Miniport Driver sample illustrates the functionality of an NDIS miniport driver without requiring a physical network adapter. @@ -31,4 +20,4 @@ To test the miniport driver, install more than one miniport driver instance. You **Note** This sample provides an example of minimal driver intended for education purposes. The driver and its sample test programs are not intended for use in a production environment. -For more information on creating NDIS Miniport Drivers, see [NDIS Miniport Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff565949). +For more information on creating NDIS Miniport Drivers, see [NDIS Miniport Drivers](https://docs.microsoft.com/windows-hardware/drivers/network/ndis-miniport-drivers). |