Mobile Broadband Driver Development - 1

Mobile Broadband Driver Development

December 20, 2010

Abstract

This paper discusses how to write drivers for mobile broadband devices by using the Windows®mobile broadband driver model, which is part of Windows 7. The information in this paper is useful to independent hardware vendors (IHVs), original equipment manufacturers (OEMs), and driver developers.

This information applies for the Windows7 operating system.

References and resources discussed here are listed at the end of this paper.

For the latest information, see:

Disclaimer: This document is provided “as-is”. Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

© 2010 Microsoft Corporation. All rights reserved.

Document History

Date / Change
December 20, 2010 / Added more FAQ entries and updated resources list.
March 24, 2009 / First publication

Contents

Overview

Development Environment and Documentation

Mobile Broadband Driver Migration Path

New Mobile Broadband Driver

Existing NDIS 5.x or NDIS 6.0 Miniport Driver

Mobile Broadband Driver Development

Stage 1

Stage 2

Stage 3

NDIS 6.20 Changes

Raw IP Frame Processing

IP Helper APIs

Mobile Broadband Driver Test Tools

WwanDriverTestApp

Windows 7 Network UI

Mobile Broadband Logo Test

Mobile Broadband Packet Capture

Frequently Asked Questions

Resources

Overview

The Windows®mobile broadband driver model defines the standard for drivers to integrate with and to use the native mobile broadband functionality in the operating system. This paper discusses how to develop a new driver or port an existing driver to the mobile broadband driver model.

You should already be familiar with the Windows mobile broadband driver modelthat is described in the Windows 7 Windows Driver Kit (WDK) documentation. A link to this documentation on MSDN® is provided in “Resources” at the end of this paper.

The “Frequently Asked Questions” (FAQ) section of this paper answers common questionsthat relate to mobile broadband driver development.

Development Environment and Documentation

The mobile broadband driver model documentation and the development environment are available in the Windows 7 WDK. The documentation is also available onlineon MSDN.

The following header files in the Windows 7 WDK are important for mobile broadband drivers:

  • WDK-Installation Folder>\inc\ddk\wwan.h
  • WDK-Installation Folder>\inc\ddk\ndiswwan.h

Wireless wide area network (WWAN) is another namefor mobile broadband. This document uses mobile broadband, but some header files and constants use the WWAN acronym.

Mobile Broadband Driver Migration Path

Before Windows 7, a mobile broadbanddevice was supported by either a modem driver or by an NDIS 5.x or NDIS6.0 miniport driver. This section outlines the steps to port an existing modem driver, to port an existing NDIS driver, or to develop a new driver by using the mobile broadband driver model.Figure 1 shows the steps for developing a driver.

Figure 1.Mobile broadband driver migration path

The following sections describe the steps to develop a driver, depending on whatcode is already written, if any.

New Mobile Broadband Driver

If you are writingadriver from scratch or if you already have a modem-based driver,then start your mobile broadband driver by writing an NDIS6.0 miniport driver. In the interest of getting your driver up and running, we suggest that you write your driver to the NDIS 6.0 model first and add the NDIS 6.20 features later.

Use the latest WDK for developing a new NDIS 6.0 miniport driver. The following parts of the WDK will be especially helpful to you when you develop your driver:

  • Descriptions of the NDIS 6.0 interfaces and other general driver application programming interfaces (APIs).
  • The development environment, whichprovides header files and tools for developing drivers.
  • Sample code for NDIS miniport drivers in the src/network/ndis directory.
  • ”Getting Started with Windows Drivers,”which covers important topics for developing new driverssuch asdriver installation, Plug and Play, and power management.

An existing modem driver might implement Dynamic Host Configuration Protocol (DHCP) spoofing and Address Resolution Protocol (ARP) request processing. You can use this functionality in the early stages of your driver. Later, when you complete the mobile broadband driver model implementation, you shouldremove DHCP spoofing and ARP emulation as described in “NDIS 6.20 Changes” later in this document.

If you are not starting with a driver that implements DHCP spoofing and ARP processing, useNDIS 6.20 raw IP frame processing and IP helper APIs instead.These features aredescribed in “NDIS 6.20 Changes” later in this document.

When the NDIS6.0 driver is complete, test network data transfers by using the driverto ensure that the data path is working correctly.

After you complete and test the basic NDIS6.0 driver, implementthemobile broadband control functionality as defined in the mobile broadband driver model. The “Mobile Broadband Driver Development”section later in this document describes how to implement and test the mobile broadbandfunctionality in stages.

Existing NDIS5.xor NDIS6.0 Miniport Driver

If an NDIS5.1 miniport driver already exists for the mobile broadband device, then your first step is to upgrade the driver from NDIS5.x to NDIS6.0. For information on how to upgrade a miniport driver to NDIS 6.0, see “Porting NDIS 5.x Drivers to NDIS6.0.”

When the NDIS6.0 driver is ready, test network data transfer to ensure that the data path is working correctly with NDIS6.0. You can test data transfer by browsing on the Internet or transferring a file over the mobile broadband connection.

The next step is to implement themobile broadband control functionality as defined in the mobile broadband driver model. The “Mobile Broadband Driver Development” section later in this document describes how to implement and test the mobile broadbandfunctionality in stages.

Note thatan NDIS5.xor NDIS6.0 miniport driver probably implements DHCP spoofing and ARP processing. You can use this functionality in the early stages of your driver.Later,after you complete the mobile broadbanddriver model implementation, you can remove DHCP spoofing and ARP emulation as described in “NDIS6.20 changes” later in this document.

Mobile Broadband Driver Development

This section describes the steps to addmobile broadband driver model support in a working NDIS6.0 miniport driver.

The mobile broadband driver model defines NDIS object identifiers (OIDs) and indication-based communication between the mobile broadband service and mobile broadbandminiport drivers. (The mobile broadband service is the Windows component that manages mobile broadband connectivity.) Some of these OIDs and indications are required for basic driver operation, such as network connect andnetwork disconnect.Other OIDs and indications are required for additional functionality and enhanced user experience.

We suggest that you develop your driver in multiple stages, to make it easier to develop, track, and test. In stage1, implement the OIDs and indications that are required for basic driver functionality. In stage2,implement the rest of the OIDs and indications. In stage3,update your driver for NDIS 6.20 support, such as removing DHCP spoofing and ARP emulation support. These stages and tasks are described in the following sections.

Stage 1

Table 1 lists the OIDs and indications thatare required for basic connect/disconnect to work. In the first stage of development,implement these OIDs and indications. After you implement them,your driver can use the Windows7 native user interface for the connect/disconnect experience.

Table 1.OIDs and Indications to Implement in Stage 1

Query and its asynch response (if any) / Set and its asynch response
OID_GEN_MEDIA_SUPPORTED
OID_GEN_PHYSICAL_MEDIUM
OID_GEN_SUPPORTED_LIST
OID_WWAN_DRIVER_CAPS
OID_WWAN_DEVICE_CAPS
OID_WWAN_READY_INFO
OID_WWAN_HOME_PROVIDER
OID_WWAN_REGISTER_STATE (Only auto network selection mode in stage1)
OID_WWAN_PACKET_SERVICE / OID_WWAN_PACKET_SERVICE
OID_WWAN_CONNECT / OID_WWAN_CONNECT

The mobile broadband driver model defines OIDs that the driver must support and must return in response to OID_GEN_SUPPORTED_LIST. Support for these OIDs is required for the mobile broadband service to recognize the device as a mobile broadband device.

In stage1 of driver development, your driver does not implement all required OIDs. To function correctly at this stage, your driver should return all required OIDsin response to OID_GEN_SUPPORTED_LIST. Your driver should synchronously return error code NDIS_STATUS_NOT_SUPPORTED from its MiniportOidRequestfunction for the OIDs that have not yet been implemented.

To verify driver implementation at the end of stage1 of development, perform the following tests:

  • Validate the stage 1 OIDs and indications by using WwanDriverTestApp.
  • Verify that the Windows network user interface (UI) shows the mobile broadbandnetwork for the connect/disconnect operation and verify that connect/disconnect works with the Windows network UI.
  • Test network browsing to ensure that no regression occurred in the data path.
  • Verify the implemented OIDs and indications by using the logo tests for mobile broadband. All the tests for OIDs and indications that you have implemented should pass. The tests for the OIDs and indications that you will implement later will fail, as expected.
  • Verify that the driver handles Plug and Play requests correctly by dynamically plugging in and removing the device.
  • Verify that the driver handles power management requests correctly by testing the system sleep/hibernate cycle and the system wake/resume cycle with the device plugged in to the system.

For details on testing tools, see “Mobile Broadband Driver Test Tools”later in this paper.

Stage 2

In stage2 of driver development,you must implement all mandatory OIDs and indications that are defined in the mobile broadband driver model.

Youmight also implement the optional OIDs and indications if they apply to the functionality that your device supports. For example, OID_WWAN_SERVICE_
ACTIVATION is an optional OID, but if yourdevice supports service activation,then your driver should implement this OID in stage 2.

To verify driver implementation at the end of stage2 of driver development, perform the following tests:

  • Validate all OIDs and indications by usingWwanDriverTestApp.
  • Confirm that the following operations are possible by using the Windows network UI:
  • Basic connect/disconnect.
  • PIN lock and unlock operations.
  • Manual network selection for roaming networks.
  • Correct signal strength should be visible in the UI.
  • The network UI should show the refreshed state in response to changing network conditions. For example, a change from one network to another while roaming should reflect the new operator name.
  • Test network browsing to ensure that no regression occurred in thenetwork data transfer functionality.
  • Run the mobile broadband Logo tests to verify the implemented OIDs and indications. Most of the test cases should pass because most functionality should be implemented by the end of stage2. The only tests that should fail are those that test NDIS 6.20 changes that you will implement in stage 3.
  • Test Plug and Play and power management functionality,as you did at the end of stage 1.

Stage 3

In the last stage of development,migrate your driver from NDIS6.0 to NDIS6.20. The following NDIS6.20 changes are important formobile broadband drivers:

  • Disable DHCP emulation and ARP processing in the driverand use the new IP helper APIs.
  • Implement RAW IP frame processing.

For more information on these changes, see “NDIS 6.20 Changes” later in this document.

After successful completion of stage 3 development,perform stage 2 testing again to ensure that no regressionsoccurred because of NDIS6.20 changes.

After successful completion of stage3 testing, your driver is ready for Windowslogo certification.Run the NDIS logo test tools to ensure driver quality and then submit your driver for logo certification.

NDIS 6.20 Changes

This section summarizesthe main NDIS6.20 changes that are related to mobile broadbandminiport drivers. The most important changes for mobile broadband miniport drivers areas follows:

  • Raw IP frame processing.
  • IP helper APIs.

Figure 2 shows the differences between an NDIS 6.0 mobile broadband driver and an NDIS 6.20 driver.

Figure 2.NDIS 6.20 changes for mobile broadband drivers

Refer to the NDIS6.20 documentation on MSDN and in the WDK for a complete list of required changes for porting an NDIS6.0 miniport driver to NDIS6.20. The following sections describe the NDIS 6.20 changes that are specific to mobile broadband devices.

Raw IP FrameProcessing

Windows Vista® and earlier versions of Windows had no specific medium type for mobile broadband networks. On these systems, mobile broadband miniport drivers exposed their medium as 802.3 (Ethernet). This required drivers to perform ARP request processing and Ethernet frame handling as expected from Ethernet networks. But mobile broadband networks are point-to-point and do not require ARP emulation or Ethernet frame handling.

In Windows 7,NDIS 6.20 defines a new media type:NdisMediumWirelessWan. For this media type, the operating system directly sends raw IP packets to the miniport driver and expects RAW IP framesto be returned from the miniport driver. Because Ethernet frames are not used for this media type, ARP translation is unnecessary. This relieves the miniport driver from processing the ARP request or Ethernet frame handling. For details about Raw IP frame processing, refer to the mobile broadband WDK documentation. You can find a link to the mobile broadband documentation in “Resources.”

IP Helper APIs

Mobile broadband drivers use 3GPP- and 3GPP2-defined standards to retrieve IP connection settings (IP address, Gateway, and Domain Name Service [DNS] address) from the network. The drivers then implement a DHCP server in the driver or device firmware to communicate with the operating system about the connection settings that use DHCP protocol. Requiring drivers to implement a DHCP server increases the complexity of drivers.

In Windows7, mobile broadband drivers should use the new system-provided IP helper APIs to notify the operating system of the connection settings. Drivers should use these APIs and are not required to implement a DHCP server in the driver or firmware.

For more details about how to use the IP helper APIsto set connection parameters, refer to the mobile broadband WDK documentation.

Mobile Broadband Driver Test Tools

This section describes tools for testingmobile broadband drivers.

WwanDriverTestApp

You can use WwanDriverTestApp to send OID requests to adriver and receive transactional and unsolicited indications from the driver.

This application doesnot validatedriver responses. It only sends and receives responsesto and from the driver. You must manually verify the responses. WwanDriverTestAppis very useful in the initial development phase because you can use it to test each OID and indication with no dependency on the implementation of other OIDs.

WwanDriverTestApp is available in the Windows 7 WDK. Figure 3is a screenshot of this application.

Figure 3. The WwanDriverTestApp test application

This screenshot shows an OID request that was sent to a miniport driver (query OID_WWAN_RADIO_STATE) and the indications that were received from the driver.

Windows 7 Network UI

After you have implemented all the OIDs and indications that are suggested in stage1 of driver development, you can use the Windows network UI to perform basic integration testing of yourdriver with Windows 7.

Access the network UI from the Network Tray icon in the taskbar. Figure 4 shows a screenshot of the network UI.

The network UI lets you connect to, and disconnect from, the network by using a native UI.

Figure 4. Windows 7 network UI

Mobile Broadband Logo Test

The mobile broadbanddevice tests are part of the WindowsLogo Kit (WLK) for Windows 7. It is an automated test suite that verifies the driver functionality that is related to mobile broadband.To receive Windows logo certification, your driver must successfully complete a full pass of the mobile broadbandlogo tests.

You can distribute a logo-certified driver through Windows Update (WU). To support the Windows 7 mobile broadband driver model, some devices mightrequire a firmware upgrade along with driver installation.If your mobile broadbanddriver upgrades the firmware as part of driver installation through WU, your installationmust ask for user consent before it upgrades the firmware. The driver installation should fail if the user chooses not to upgrade the firmware.

Mobile Broadband Packet Capture

You can use the latest release of the Network Monitor, Version 3.3 Beta, to capture and analyze mobile broadband packet traffic. You can find a link to the Network Monitor (netmon) tool in “Resources.”

Figure 5. Mobile broadband packet analysis with netmon

Frequently Asked Questions

This section provides answers to some common questions about how to develop a mobile broadband miniport driver.

Can the existing modem interface that a device exposes be used to implement an NDIS miniport driver that follows the mobile broadbanddriver model?

Many mobile broadbanddevices are currently exposed to the system as modem devices. A modem device supports the AT command interface for configuring and managing the device. A mobile broadbandNDIS miniport driver can reuse the underlying modem interface to implement the OIDs and indications that are defined in the mobile broadbanddriver model. The common approach is to have the mobile broadbandminiport driver communicate with the underlying modem driver by using the device's COM port.