SUMMARY
MUX Intermediate Miniport Driver
The MUX Intermediate
Miniport (IM) driver is an NDIS 5 driver that demonstrates the operation of an
“N:1” MUX driver, i.e. one which 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
framework are Virtual LAN (VLAN) drivers.
This sample implements
IEEE 802.1Q VLAN tagging, which is enabled by changing the default VLAN ID to a
non-zero valid value (see “Configuring VLANs” below).
Operation
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.
When it binds to a lower
adapter, MUX reads the standard “UpperBind” key to obtain a list of VELANs
configured over this adapter. For each such VELAN, it calls NdisIMInitializeDeviceInstanceEx()
to instantiate the NDIS miniport for the VELAN. NDIS then calls the driver’s
MiniportInitialize (MPInitialize) routine to start the VELAN miniport.
The MUX driver supports
configuring the MAC address for each VELAN miniport using the standard
“NetworkAddress” key that it reads from its MiniportInitialize routine. If this
is not configured, it computes a “locally significant” MAC address for the
VELAN using the MAC address of the lower adapter. The MUX driver sets its lower
adapter to promiscuous mode in order to be able to receive frames directed to
any of the VELAN MAC addresses. However it does implement
packet-filtering (and multicast address filtering) logic for all its VELAN
miniports so that it only passes up relevant frames on each VELAN. This
aspect of the driver may be modified if, for example, your driver design uses
the same MAC address as that of the lower adapter on all VELANs. With such a
modification, it is not required to set the lower adapter to promiscuous mode
and incur the costs of receiving all packets on the network.
It supports dynamic
addition and deletion of VELANs in conjunction with its
notify object (related sample). If a VELAN is deleted, the virtual device
corresponding to the VELAN is stopped and removed, which in turn results in
NDIS halting the miniport instance for the VELAN (see MPHalt). If a
VELAN is added, NDIS sends a global reconfiguration event to the protocol edge
of this driver. The handler function for this event, PtPNPHandler, goes through
all lower adapters to see if any new VELANs have been added, i.e. if any of the
“UpperBind” keys have been modified.
Since the driver
implements a virtual device, it does not simply pass through most NDIS
queries/sets. It keeps its own device view that is reflected in its responses
to queries/sets. However it does pass through queries/sets for certain OIDs
that are best handled by the lower adapter driver.
The driver supports Power
Management in the sense that it allows Wake-On-LAN and related functionality,
if supported by the lower adapter, to continue to function. It does so by
appropriately forwarding OID_PNP_XXX queries/sets to the lower adapter.
IEEE
802.1Q VLAN Operation
The driver supports
configuring a VLAN ID on each VELAN. It then inserts a tag header containing
this VLAN ID on all outgoing frames. For incoming frames that contain a tag
header, it verifies that a matching VLAN ID is present before indicating it up
to protocols. It removes the tag header, if present, from all indicated frames.
In all cases, received frames that do not contain tag headers are always handed
up to protocols.
With the default
configured VLAN ID of zero, the driver does not insert tag header information
on sent packets, except for sent packets that contain non-zero Ieee8021QInfo
per-packet information, for which the driver does insert corresponding tag
headers. Receive-side filtering on VLAN ID is enabled only with a non-zero
configured VLAN ID, in which case only received frames containing a matching
VLAN ID are passed up. With the default configured VLAN ID of zero, the driver
does not check the VLAN ID on received frames.
BUILDING THE SAMPLE
Run the build
command from this directory to build the sample—it creates the binary mux.sys.
To disable IEEE VLAN support, comment out the following line in the sources
file before building:
C_DEFINES=$(C_DEFINES)
–DIEEE_VLAN_SUPPORT=1
To install this driver on
Windows® codename Whistler, use the MUX sample notification object and INFs,
also found in this DDK.
INSTALLING THE SAMPLE
MUX is installed as a
protocol (called “Sample Mux-IM Protocol Driver” in
the supplied INFs/notification object). To install, follow the steps below.
Prepare a floppy disk (or
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).
On the desktop,
right-click the My Network Places icon and choose Properties.
Right-click on the
relevant Local Area Connection icon and choose Properties.
Click Install,
then Protocol, then Add, then Have
Disk.
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.
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.
Configuring
VLANs
The VLAN ID for each
VELAN (virtual miniport) can be configured as follows. Right-click on the
virtual miniport Local Area Connection icon and choose Properties. Click on the Configure
button to bring up the Device Manager UI for the virtual device. Select the Advanced property sheet – this should
contain a “VLAN ID” parameter that is configurable to the desired VLAN ID.
Choosing a value of 0 (zero) disables receive-side filtering based on VLAN ID.
CODE TOUR
File Manifest
File Description
Makefile Used during compilation to create the object and sys files
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.htm Documentation for the MUX driver (this file)
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
Sources List of source files that are compiled and linked to create the MUX driver. This can be modified to create binaries that operate on previous Windows versions (e.g. Windows 2000).
Programming Tour
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
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 (i.e. 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
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.
PtUnbindAdapter itself blocks until all VELANs
associated with the ADAPT structure have been unlinked from it. This is to make
sure that no thread running in the context of a miniport-edge entry point for a
VELAN will ever access an invalid lower binding handle. Once all VELANs have
been unlinked, PtUnbindAdapter closes the lower binding by calling
NdisCloseAdapter. Note that the MUX driver does not close its lower binding
from any context other than its UnbindAdapter function – this is recommended
behavior for all drivers of this type.
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
MPQueryInformation 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
MPSetInformation 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).
Note that setting the lower
adapter to promiscuous mode is only done here in order to be able to receive unicast frames directed to multiple MAC addresses. If, for
example, all VELANs are assigned the same MAC address (which is identical to
the address of the lower adapter), then the MUX driver should only pass down
the combined (bitwise OR) setting of packet filter settings of all VELANs.
Some power management OIDs are
forwarded to the lower miniport. See “Handling Power Management” below for details.
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 allocates a new NDIS_PACKET for each packet
passed to its MPSendPackets function, and saves a pointer to the
original NDIS_PACKET in the reserved area of the packet structure. When the
lower adapter completes the send (PtSendComplete), MUX picks up the
original packet and calls NdisMSendComplete 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
Data received from a lower adapter
is indicated up on zero or more VELANs. The PtReceivePacket or PtReceive
function is called for each packet received from the lower adapter. In both
cases, 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 NDIS_PACKET is allocated and set to point to
the received data. A pointer to the original received packet (if any) is also
stored in the new packet’s reserved area. This packet is indicated up via
NdisMIndicateReceivePacket to all interested protocols on that VELAN.
The driver’s MPReturnPacket
function is called either by NDIS or by MUX itself when protocols are done with
a received packet. This function returns the original packet indicated by the
lower driver, if any, by calling NdisReturnPackets.
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 NDIS_PACKET structures.
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
During initialization (MPInitialize),
the MUX miniport sets the attribute NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND in
its call to NdisMSetAttributesEx. 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:
NDIS_DEVICE_POWER_STATE MinMagicPacketWakeUp =
NdisDeviceStateUnspecified;
NDIS_DEVICE_POWER_STATE MinPatternWakeUp=
NdisDeviceStateUnspecified;
NDIS_DEVICE_POWER_STATE MinLinkChangeWakeUp=NdisDeviceStateUnspecified
See PtPostProcessPnPCapabilities
for details.
OID_PNP_SET_POWER and
OID_PNP_QUERY_POWER are not passed to the lower adapter, since the lower layer
miniport will receive independent requests from NDIS.
NDIS calls the MUX driver’s
ProtocolPnPEvent function (PtPNPHandler) whenever the underlying adapter
is transitioned to a different power state. If the underlying adapter is
transitioning to a low power state, the driver waits for all outstanding sends
and requests to complete.
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
All modifications to VELAN
configuration are accompanied by PnP reconfigure notifications, i.e.
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 exist – see PtBootStrapVElans
for details.
NDIS 5.1 Features
The NDIS 5.1 features in MUX are
identified by #ifdef NDIS51 compiler directives. The following feature is
illustrated (refer to the DDK documentation for more information on these):
Canceling Sends: MUX propagates send
cancellations from protocols above it to lower miniports.
Top of page
© 1999 Microsoft
Corporation