 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
Microsoft Corporation
April 2000
Summary:The objective of this white paper is to provide an overview of the Network Driver Interface Specification (NDIS) architecture in Microsoft Windows CE and the relevant information to write NDIS drivers for Windows CE. For the most part, this may indeed involve porting an NDIS Miniport driver from Windows NT to Windows CE operating system. This paper starts with a brief introduction to NDIS, and then moves onto describing the support for NDIS in Windows CE and the details of writing an NDIS Miniport driver. (14 printed pages)
Contents
Introduction
At the outset, the reader should note that the Microsoft Windows
CE NDIS implementation is a subset of NDIS 4.0 implementation used
in Windows NT operating system. Hence, you should consult the
Microsoft Windows NT version 4.0 Driver Development Kit for
complete documentation on NDIS architecture and all network
connectivity issues. The documentation in the Windows CE Driver
Development Kit only supplements the Windows NT documentation. This
white paper references the documentation in both these
toolkits. NDIS describes the interface by which one or more Network
Interface Card (NIC) drivers communicate with one or more
underlying network interface cards, with one or more overlying
protocol drivers, and with the operating system. NDIS defines a
fully abstracted environment for NIC driver development. For every
external function that a NIC driver needs to perform, it can rely
on NDIS routines to perform the operation. This includes the entire
range of tasks performed by a NIC driver, from communicating with
protocol drivers, to registering and intercepting NIC hardware
interrupts, and communicating with underlying NICs by manipulating
registers, port I/O, and so forth. Therefore, NIC drivers can be
written entirely in platform-independent high-level languages such
as C. These drivers can then be recompiled with a system-compatible
compiler to run in any NDIS environment. To provide this level of abstraction and portability, Windows NT
provides an NDIS export library referred to here as the NDIS
library or NDIS. All interactions between a NIC driver and protocol
drivers, a NIC driver and the operating system, and a NIC driver
and the network adapters that it controls are through calls to NDIS
functions. NDIS is packaged in an export library as a set of
functions, with emphasis on in-line macros for maximum performance.
All NDIS drivers, including highest-level NDIS protocol drivers,
intermediate NDIS drivers, and NIC drivers link against this
library. When called, an NDIS function calls an associated function
in a higher-level driver, in an intermediate NDIS driver, in a NIC
driver, in the operating system, or else performs an
internal-to-NDIS local action. As mentioned earlier, the NDIS implementation on Windows CE is a
subset of the NDIS 4.0 implementation used on Windows NT. The
differences between the Windows CE and Windows NT implementations
are described later in this document. The complete NDIS
specification supports several types of network drivers, but
Windows CE version 2.0 and later only support writing NDIS Miniport
drivers, not monolithic or full Network Interface Card (NIC)
drivers. For NDIS Miniport drivers, Windows CE is source code compatible
with Windows NT. This means that, with a few exceptions, Windows CE
and Windows NT support identical NDIS APIs. You can consult the
Microsoft Windows NT Version 4.0 Driver Development Kit for full
documentation regarding NDIS APIs and for extended information on
how to write a Miniport driver. Although the documentation in
Windows CE Driver Development Kit provides supplementary
information pertaining to Windows CE NDIS Miniports, it does not
discuss at length the process of writing Miniport drivers. This
white paper tries to bridge that gap by providing as many details
as possible on writing NDIS Miniport drivers. For a complete list
of NDIS APIs supported by Windows CE, including documentation on
the minor differences between Windows CE APIs and their Windows NT
counterparts, consult the reference contained in this Windows CE
Driver Development Kit. Windows CE version 2.0 provided support for writing or porting
Ethernet (802.3) Miniport drivers from Windows NT. Windows CE
version 2.1 now supports writing or porting Windows NT IrDA
Miniport drivers. To summarize, here is a list of the key features of NDIS support
in Windows CE.
There are several NDIS Miniport driver samples that are shipped
in the Windows CE Embedded Toolkit and they are listed below. A
driver developer should consult the following sample code to better
understand the concept of writing an Ethernet or IrDA NDIS Miniport
driver on Windows CE.
For example we provide an NE2000 sample that works with any
NE2000-compatible network adapter. In Windows CE version 2.0, our
NE2000 sample driver supported the PCMCIA bus, in Windows CE
version 2.1 it supported the PCI bus, and in Windows CE version
2.11 it now supports the ISA bus. We have also added 3 more
Miniport sample drivers in Windows CE version 2.1. A Proxim driver
for Proxim wireless Ethernet PC Card devices, a Xircom driver for
Xircom Ethernet PC Card devices, and a Fast IR driver for Fast IR
network cards that are based on the National Semiconductor PC87338
chipset. In addition, in Windows CE version 2.0, we shipped another
sample driver namely the Serial IR Miniport driver - this driver is
the only example of an Intermediate NDIS Miniport driver in Windows
CE. In our internal testing at Microsoft, note that we have
observed transfer rates of up to 4 MBps with our Fast IR driver and
115 KBps with our Serial IR driver, which is consistent with the
Fast IR and Serial IR specifications. Another key point is that the
IrDA protocol in Windows CE auto negotiates baud rates such that
both Serial IR and Fast IR devices can inter-operate on the same
device. Figure 1 below shows an overview of the NDIS architecture in
Windows CE. The NDIS architecture consists of several components:
Figure 1. NDIS Driver Architecture in Windows CE
Figure 2 below illustrates a more detailed Networking
architecture in Windows CE, by using an example network
configuration. There are two NDIS protocol drivers: TCP/IP and
IrDA. Each protocol driver is bound to a single Miniport driver in
this diagram. The IrDA protocol driver is bound to IrSIR -- the
serial IR intermediate Miniport. The TCP/IP protocol driver is
bound to an NE2000 Miniport driver. Windows CE does not support
NDIS WAN, instead TCP/IP binds directly to the PPP component which
interfaces directly with serial driver for modem and direct-cable
connections.
Figure 2. Example networking configuration in Windows CE
There are several differences between Windows CE and Windows NT
implementations of NDIS Miniports. This section highlights some of
these differences.
For sample DriverEntry implementations, see the source code for
the sample Miniport drivers provided in the Embedded Toolkit.
A Miniport driver on Windows CE must provide some additional
code for Power Management considerations. These considerations are
based on whether the network card is a PC Card NIC or built-in NIC.
In addition, note that a PC Card NIC may be removed at any time
from the device, so the NDIS Miniport driver should have timeouts
on all operations that poll the card's registers.
If more explicit power handling is required (i.e. to power off
the peripheral from the Miniport), the Miniport could register
itself as a Stream Interface driver and receive notifications on
Power-Down and Power-Up system events. This option should only be
required if the platform does not perform the necessary power
handling of the peripheral in the OAL. Also, Miniport drivers which
register as Stream Interface drivers should not call any NDIS
functions in the power handler except raw I/O functions. For more
information on restrictions in power handling for Stream Interface
drivers, please refer to the Windows CE Driver Development Kit.
If the Miniport is not concerned with such power management, the
Miniport can initialize with all resources and treat the set/query
OID requests as null operations. This decision is made based on the
requirements of the WCE target platform.
Unlike Windows NT, the Windows CE implementation of NDIS does
not inherently support DMA operations. There are two methods
depending on whether the NIC is a slave-DMA NIC or a busmaster-DMA
NIC.
The NSC IrDA miniport sample code in Windows CE 2.1 implements
slave-DMA for an 8237 DMA Controller for FIR data transfer in the
miniport. In the sample code, the miniport has a physical memory
block (reserved from device's memory map) which is mapped to
virtual address pointers using VirtualAlloc/VirtualCopy. The
miniport then has a shared memory block for send and receive packet
buffers: virtual address pointers for use in the miniport and
physical addresses for setting up the DMA controller.
In general for a Windows NT miniport, data received by a
busmaster-DMA NIC is transferred directly into device-accessible
buffers within a shared memory block allocated by the miniport. The
miniport calls NdisMInidcateReceivePacket to indicate the packet to
the protocol. A Windows CE miniport would likely use the same
implementation for the receive path. Shared memory blocks may be
setup as described above in the slave-DMA NIC section.
To transfer packet data for a send request, a Windows NT
miniport basically does the following:
For small send requests (< 256 bytes), the miniport can
possibly achieve higher performance by copying the bytes into a
shared memory buffer, since the Miniport then does not need to map
the protocol's send buffer.
On Windows CE, a Miniport can use the functions
LockPages/UnlockPages in place of the NDIS functions,
NdisMStartBufferPhysicalMapping and
NdisMCompleteBufferPhysicalMapping, for mapping virtual addresses
to physical address ranges.
Windows CE does not support the Common Network INF file format
for installing devices drivers that is used in Windows NT. Instead,
Windows CE uses the Registry file for dynamically installing and
binding all Driver Developments. Hence, you must ensure that
appropriate registry key settings are created for your Miniport
driver in the Windows CE registry. There are several Registry key settings that are common to both
built-in and PC Card type of Miniports. However, there are some
distinct settings that apply to each type and you must pay careful
attention to them. This section describes these settings in detail.
Note that the TCP/IP protocol stack supports Miniports for both
built-in and PC Card Ethernet hardware. The TCP/IP protocol may
bind to multiple Miniport driver instances - allowing it to use
multiple NICs. The IrDA protocol stack may only bind to one
built-in Miniport driver instance. When a Miniport driver is installed on a Windows CE-based
platform, the setup program should create several registry keys in
order to correctly expose the Miniport driver to the Windows CE
system. These common registry settings provide driver-specific
information to the OS - such as, Miniport type (Group=NDIS), the
driver name, driver instance(s), and other information like bus
type and number. Windows CE will load all the NDIS drivers listed
within the HKEY_LOCAL_MACHINE\Comm\ key, where each key is any
arbitrary string value identifying the Miniport driver. Each
Miniport\ key contains the following subkeys. The value of the Linkage\Route key lists subkeys for each
Miniport instance. These subkeys in turn contain keys called
BusNumber and BusType, which correspond to the bus used by that
particular Miniport driver instance. BusNumber values start at 0.
Valid BusType values are declared in the header file CEDDK.H. The
following example shows a set of registry keys for a Miniport
driver. At Windows CE system boot time, NDIS interface will load all the
drivers under HKEY_LOCAL_MACHINE\Comm that has "Group" value set to
"NDIS". Then, NDIS calls the DriverEntry entrypoint function in
each Miniport driver. When the driver registers as a Miniport via
the NdisMRegisterMiniport function, then the initialize handler of
the Miniport is called. Built-in Miniports are bound to a protocol by indicating the
linkage associated with the protocol in the registry. For Ethernet
Miniports: Note that the TCP/IP linkage registry key may indicate for IP to
bind to a PPP interface as well. Below is an example that shows the
NE20001 Miniport instance and the PPP interface being bound to the
TCP/IP protocol. For IrDA Miniports, the following is the registry key that is
used. Below is an example that shows the Serial IR Miniport driver
being bound to the IrDA protocol via the Linkage registry key. In addition, PC Card Miniport drivers require an
HKEY_LOCAL_MACHINE\Drivers\PCMCIA\Plug-and-Play ID\ registry key.
This key typically is named after the Plug and Play ID of the PC
Card, but this is not a requirement. The key contains the following
subkeys. For example, a PC Card network adapter could have the following
additional keys. The NDIS Interface sets values for the BusNumber and BusType
keys for PC Card network adapters. The BusNumber key will contain
the socket and function pair for the network adapter. The BusType
key will contain the value for the PC Card bus. Finally, if the
card information structure (CIS) of the PC Card contains a network
address value, NDIS.dll will create a
\HKEY_LOCAL_MACHINE\Comm\<Miniport Name>\<Miniport
Instance>\Network Address key to store the network address. When a recognized PC Card NIC is inserted, PC Card Services
calls NDIS to load the Miniport driver. NDIS calls the DriverEntry
routine. As with the built-in Miniport drivers, the DriverEntry
routine registers the driver as a Miniport and the driver's
initialize handler is called. Once the Miniport is initialized,
NDIS calls the bind adapter handler for TCP/IP, which subsequently
calls NdisOpenAdapter to setup the binding between the Miniport and
the protocol. The binding is only established if the supported
media of the protocol and the Miniport match. And finally, PC Card Miniport drivers typically implement an
Install_Driver function for installing the appropriate registry
settings that will allow for dynamic recognition and installation
of the NIC/Miniport. For example, when a NIC PC Card is inserted
into a Windows CE system, it tries to recognize the appropriate
driver for the card by matching its PnP ID with an appropriate key
in the registry. If the system fails to find a PnP match, then it
will prompt the user for a user-supplied driver name. If this
user-supplied driver DLL exports an Install_Driver function, the
system calls this function. The primary purpose of this function is
to populate the Windows CE registry with appropriate entries for
this Miniport driver, as described above, such that future
insertions of the NIC card will lead to dynamic loading of the
correct NDIS Miniport driver. The Windows NT NDIS Netcard Driver Tester program is used to
test network drivers and network interface cards in all Microsoft
operating systems. For simplicity, we will refer to the NDIS
Netcard Driver Tester program as NDISTest in this white paper. The
NDISTest program performs two important tasks: it verifies your
network interface card (netcard) and driver's operations, and at
the same time ensures that your product conforms to the Network
Driver Interface Specification (NDIS) version 4.0. Note that NDIS
3.0 drivers are no longer being certified for Windows NT or Windows
9x or Windows CE. NDISTest verifies the functionality of each NDIS request
supported by the netcard driver. The tester works by stressing the
packet send and receive functions. The tester emulates a transport
layer protocol driver and communicates with the netcard driver
through the NDIS wrapper. To test a variety of network
configurations, multiple instances of the tester are be bound to
each driver. With this you can simulate up to eight network stacks
installed onto the same machine. NDISTest on Windows CE works in a manner similar to NDISTest on
Windows NT and Windows 9x. It is recommended that the reader be
familiar with Windows NT version of the NDISTest software as
documented in the Microsoft Windows NT Version 4.0 Driver
Development Kit. Primary differences between the Windows CE and
Windows NT versions are that Windows CE supports only a subset of
the tests that are available on Windows NT, and that the Windows CE
version lacks a GUI to configure and start the tests. The subset of
the tests that Windows CE supports is limited to the functional
testing of the Ethernet devices. NDISTest and all other Windows CE driver test routines are part
of the Windows CE Driver Development Test Kit (DDTK) Version 2.1
toolkit. Please refer to the DDTK 2. 1 product for complete
information on how to setup, run, and test with NDISTest on a
Windows CE platform. The DDTK toolkit was not included in the
Windows CE Embedded Toolkit version 2.1, but it is currently
available as part of the Windows CE Driver Repository. However,
later releases of the Window CE Embedded Toolkit (starting from
version 2.11) will include the DDTK toolkit. To run NDISTest requires a Windows CE device with a NIC or
netcard. This allows 1-machine functional testing to be performed.
To perform 2-machine functional testing, you will need a Windows NT
system with a netcard that is connected to a Windows CE machine
with its own netcard. It is recommended that debug output from the Windows CE device
be monitored. It is also recommended that a debugger be connected
to the CE system such that exceptions and breakpoints that are
encountered can be effectively detected and analyzed. And finally, note that NDISTest for Windows CE has been
successfully tested on x86, SH3, and Sh1 processors. It should work
on other processors, but this functionality has not been tested as
part of the shipping Windows CE operating system. Windows CE provides a wealth of tools and information on how to
debug Driver Developments and system-level OAL components in the
operating system. These debug tools and techniques can be applied
to debug NDIS Miniport drivers as well. This white paper provides a
brief description of the debug tools, but you should consult the
Embedded Toolkit documentation for further information on each of
these tools. There are 3 essential debug services that allow for
debugging Driver Development modules under Windows CE.
In addition, note that prior to Windows CE version 2.1, all the
above debug services were tied to a specific transport (for
example, debug messages and the Windbg debugger always went to the
serial port, CESH always over the parallel port, and so on). With
Windows CE version 2.1, this has been made more configurable so as
to support systems with limited capability (such as those without
parallel ports). In particular, Ethernet debug support has been
added to the operating system such that any of the debug transports
can use the high-speed Ethernet transport. Please note that debug
Ethernet support is completely different from NDIS Ethernet
support. To enable debug Ethernet support on Windows CE, you
require a dedicated Ethernet NIC, separate from the one accessed
through NDIS Ethernet services. Once you have developed and tested a NDIS Miniport driver, the
next obvious question is - "how to distribute your NDIS Miniport
driver to the majority of Windows CE customers?" In order to
facilitate such embedded and driver developers, the Windows CE
group has created the Windows CE Driver Repository program. The
Driver Repository serves the following primary purposes at this
time:
In the future, the Windows CE Driver Repository will move
towards the concept of a "Windows CE Driver Library", also known as
the CEDL. Although the Driver Library is still in the planning
stages and the implementation details are not finalized, it will
most probably consist of Windows CE Driver software that has been
verified and/or tested for the Windows CE operating system by the
Microsoft WHQL program. In essence, the main difference between the
current Driver Repository and the future Driver Library programs
would be in the WHQL certification process and possibly an
associated logo. Since we are still in the early stages of planning
the Driver Library program, interested customers should
periodically check
Microsoft Hardware Certification.
Writing NDIS Miniport Drivers
Installing and Binding NDIA Miniport
Drivers
Testing NDIS Miniport Drivers
Debugging NDIS Miniport Drivers
Windows CE Driver Repository
Introduction
NDIS on Windows NT
NDIS on Windows CE
Sample code on NDIS Miniports in Windows CE
Writing NDIS Miniport Drivers
NDIS Architecture
Differences between Windows CE and Windows NT
NTSTATUS DriverEntry(IN PDRIVER_OBJECT
pDriverObject, IN PUNICODE_STRING pRegistryPath);
Power Management Considerations
DMA Considerations
Installing and Binding NDIA
Miniport Drivers
Common Registry Keys for Miniport Drivers
Subkey
Contents
DisplayName
A user-friendly name for the driver
Group
The literal value NDIS
ImagePath
The name of the DLL containing the Miniport
driver
Linkage\Route
A set of Miniport instance keys
Miniport Instance
BusNumber and BusType keys
[HKEY_LOCAL_MACHINE\Comm\NE2000]
DisplayName="NE2000 Compatible Ethernet Driver" Group ="NDIS"
ImagePath="NE2000.DLL" [Linkage] Route="NE20001, NE20002"
[HKEY_LOCAL_MACHINE\Comm\NE20001] DisplayName="NE2000 Compatible
Ethernet Driver" Group ="NDIS" ImagePath="NE2000.DLL" [Parms]
BusNumber=0 BusType=8 [HKEY_LOCAL_MACHINE\Comm\NE20002]
DisplayName="NE2000 Compatible Ethernet Driver" Group ="NDIS"
ImagePath="NE2000.DLL" [Parms] BusNumber=0 BusType=8
Registry Keys for Built-In Miniports
[HKEY_LOCAL_MACHINE\Comm\Tcpip\Linkage] Bind =
PPP, <miniport instance>
[HKEY_LOCAL_MACHINE\Comm\Tcpip\Linkage] Bind =
PPP, NE20001
[HKEY_LOCAL_MACHINE\Comm\IrDA\Linkage] Bind =
<miniport instance>
[HKEY_LOCAL_MACHINE\Comm\IrDA\Linkage] Bind =
IRSIR1
Registry Keys for PC Card Miniports (Plug and
Play)
Subkey
Contents
DLL
The literal value NDIS.dll
Prefix
The literal value NDS
Miniport
The name of the Miniport driver for the PC Card,
which corresponds to the name of the registry key within
HKEY_LOCAL_MACHINE\Comm\ for the Miniport driver.
[HKEY_LOCAL_MACHINE\Drivers\PCMCIA\NICs-R-Us
Inc.-Super2000-E6FE] DLL="NDIS.DLL" Prefix= "NDS"
Miniport="NE2000"
Testing NDIS Miniport Drivers
NDIS Netcard Driver Tests
NDISTest on Windows CE
Debugging NDIS Miniport Drivers
Windows CE Driver Repository
Important Any driver software or
product that is published or available on the Windows CE Driver
Repository Web site is solely the property of the 3rd party OEM or
IHV vendor. They are not the property of Microsoft, nor are they
supported or endorsed by Microsoft in any way.