USB CDC/EEM Class Driver Reference Manual - Thesycon

ThesyconВ® Systemsoftware & Consulting GmbH
USB CDC/EEM Class Driver
For Windows XP, Vista, 7, 8 and 8.1
Reference Manual
Version 2.36
July 03, 2014
Thesycon R Systemsoftware & Consulting GmbH
Werner-von-Siemens-Str. 2 В· D-98693 Ilmenau В· GERMANY
Tel: +49 3677 / 8462-0
Fax: +49 3677 / 8462-18
http://www.thesycon.de
Copyright (c) 2013-2014 by Thesycon Systemsoftware & Consulting GmbH
All Rights Reserved
Disclaimer
Information in this document is subject to change without notice. No part of this manual may be
reproduced, stored in a retrieval system or transmitted in any form or by any means, electronic or
mechanical, including photocopying and recording for any purpose other than the purchaserвЂ™s personal use, without prior written permission from Thesycon Systemsoftware & Consulting GmbH.
The software described in this document is furnished under the software license agreement distributed with the product. The software may be used or copied only in accordance with the terms
of license.
Trademarks
The following trade names are referenced throughout this manual:
Microsoft, Windows, Win32, Windows NT, Windows XP, Windows Vista, Windows 7, Windows 8, Windows 8.1 and Visual C++ are either trademarks or registered trademarks of Microsoft
Corporation.
Other brand and product names are trademarks or registered trademarks of their respective holders.
Contents
Contents
Table of Contents
7
1 Introduction
9
2 Overview
11
2.1
Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
2.2
Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12
2.3
USB 2.0 support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14
2.4
USB 3.0 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14
2.5
Known Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14
2.5.1
14
Driver is not loaded after disconnect . . . . . . . . . . . . . . . . . . . .
3 Architecture
3.1
17
Special Properties of the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
3.1.1
NDIS Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
3.1.2
Surprise Removal Dialog . . . . . . . . . . . . . . . . . . . . . . . . . .
18
3.1.3
Power Management . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
3.1.4
Remote Wakeup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
3.1.5
VLAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
3.1.6
MAC Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
3.1.7
Statistic Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19
3.1.8
Multiple interfaces on one device . . . . . . . . . . . . . . . . . . . . .
19
4 Driver Customization
21
4.1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21
4.2
Reason for Driver Customization . . . . . . . . . . . . . . . . . . . . . . . . . .
21
4.3
Digital Signature for Windows Vista, Windows 7, Windows 8 and Windows 8.1 .
22
4.3.1
Using the Driver without Code Signing Certificate . . . . . . . . . . . .
22
Preparing Driver Package Builder . . . . . . . . . . . . . . . . . . . . . . . . .
23
4.4.1
Install SignTools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
23
4.4.2
Check your Code Signing Certificate . . . . . . . . . . . . . . . . . . .
23
4.4.3
Configure Certificate Variables . . . . . . . . . . . . . . . . . . . . . . .
24
4.4.4
Prepare for GUID Generation . . . . . . . . . . . . . . . . . . . . . . .
25
Using Driver Package Builder . . . . . . . . . . . . . . . . . . . . . . . . . . .
26
4.5.1
26
4.4
4.5
Customize your Driver Package . . . . . . . . . . . . . . . . . . . . . .
USB CDC/EEM Class Driver Reference Manual
5
Contents
4.5.2
4.6
4.7
4.8
Build your Driver Package . . . . . . . . . . . . . . . . . . . . . . . . .
26
Customization Parameter Reference . . . . . . . . . . . . . . . . . . . . . . . .
27
4.6.1
VENDOR_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
4.6.2
PRODUCT_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
4.6.3
DRIVER_NAME_BASE . . . . . . . . . . . . . . . . . . . . . . . . . .
27
4.6.4
INF_VID_PID_[01..16] . . . . . . . . . . . . . . . . . . . . . . . . . .
27
4.6.5
INF_VID_PID_[01..16]_DESCRIPTION . . . . . . . . . . . . . . . . .
28
Customization Default Driver Settings . . . . . . . . . . . . . . . . . . . . . . .
28
4.7.1
RxBuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
28
4.7.2
RxBuffersSubmitted . . . . . . . . . . . . . . . . . . . . . . . . . . . .
28
4.7.3
TxBuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
28
4.7.4
DefaultMediaState . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
28
4.7.5
MediaStateAfterPowerDown . . . . . . . . . . . . . . . . . . . . . . . .
28
4.7.6
DefaultXmitLinkSpeed . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
4.7.7
DefaultRcvLinkSpeed . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
4.7.8
MaxXmitLinkSpeed . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
4.7.9
MaxRcvLinkSpeed . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
4.7.10 OneByteTermination . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
4.7.11 ConfigurationIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
4.7.12 SendClearEpHaltOnStart . . . . . . . . . . . . . . . . . . . . . . . . . .
29
4.7.13 StatisticsUpdateInterval . . . . . . . . . . . . . . . . . . . . . . . . . .
29
4.7.14 VendorDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
4.7.15 TxTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
30
4.7.16 CapWakeOnMagicPacket . . . . . . . . . . . . . . . . . . . . . . . . .
30
4.7.17 CapWakeOnLinkUp . . . . . . . . . . . . . . . . . . . . . . . . . . . .
30
Advanced Dialog Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .
31
4.8.1
VLAN ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
31
4.8.2
PriorityVLANTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
31
4.8.3
WakeOnMagicPacket . . . . . . . . . . . . . . . . . . . . . . . . . . . .
31
4.8.4
WakeOnLinkUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
32
5 Driver Installation and Uninstallation
5.1
6
33
Driver Installation for Developers . . . . . . . . . . . . . . . . . . . . . . . . .
33
5.1.1
Installing CDC/EEM Driver Manually . . . . . . . . . . . . . . . . . . .
33
5.1.2
Uninstalling CDC/EEM manually . . . . . . . . . . . . . . . . . . . . .
34
USB CDC/EEM Class Driver Reference Manual
Contents
5.2
Installing CDC/EEM driver for End Users . . . . . . . . . . . . . . . . . . . . .
35
5.2.1
35
Installing CDC/EEM driver with the PnP Driver Installer . . . . . . . . .
6 Debug Support
6.1
6.2
37
Event Log Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
37
6.1.1
Clear Feature Endpoint Halt . . . . . . . . . . . . . . . . . . . . . . . .
37
6.1.2
Demo is Expired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
37
Enable Debug Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
37
7 Related Documents
USB CDC/EEM Class Driver Reference Manual
41
7
1 Introduction
1 Introduction
The CDC/EEM driver is a generic device driver for Windows that creates a Network Interface. On
the USB layer, it expects a device with a Communication Device Class (CDC) Ethernet Control
Model (EEM) compliant interface.
This document describes the architecture and the features of the CDC/EEM device driver. Furthermore, it includes instructions for installing and using the device driver.
The reader of this document is assumed to be familiar with the specification of the Universal Serial
Bus Version 2.0 and 3.0 and the CDC/EEM specification.
USB CDC/EEM Class Driver Reference Manual
9
2 Overview
2 Overview
2.1 Platforms
The CDC/EEM driver package contains 32 bit and 64 bit versions. The driver supports the following operating system platforms:
вЂў Windows 8.1
вЂў Windows 8
вЂў Windows 7
вЂў Windows Vista
вЂў Windows XP
вЂў Windows Embedded 8.1 Industry/Pro
вЂў Windows Embedded 8 Standard
вЂў Windows Embedded Standard 7 (WES7)
вЂў Windows Embedded Enterprise 7
вЂў Windows Embedded POSReady 7
вЂў Windows XP embedded
вЂў Windows Server 2012 R2 for Embedded Systems
вЂў Windows Embedded Server
вЂў Windows Server 2012 R2
вЂў Windows Server 2012
вЂў Windows Home Server 2011
вЂў Windows Server 2008 R2
вЂў Windows Server 2008
вЂў Windows Server 2003
вЂў Windows Home Server
USB CDC/EEM Class Driver Reference Manual
11
2 Overview
2.2 Features
The CDC/EEM driver provides the following features:
вЂў USB Support. The CDC/EEM driver supports USB 3.0, USB 2.0 and USB 1.1. It supports
low, full, high and super speed mode. For USB 3.0 controllers Microsoft has released the
bus driver with Windows 8. Different USB 3.0 host controllers, often with their own bus
drivers, are available on the market. Thesycon does not guarantee that the CDC/EEM runs
with all solutions.
вЂў NDIS Support. Exposes a network adapter interface according to the NDIS 5.1 model for
Windows XP and Vista and the NDIS 6.2 model for Windows 7 and 8. Windows 2000
requires the NDIS 5.0 model and is no longer supported in this version. For support, ask
Thesycon.
вЂў Plug&Play. The CDC/EEM driver fully supports hot plug and play.
вЂў Power Management. The driver supports the Windows power management model. The
network adapter does not stop when the PC enters standby, sleep or hibernate. A device
with Auto-IP address negotiation is not required to restart the negotiation after resuming
from a power down state.
вЂў Remote Wake-up Support. When the device indicates the remote wake-up feature in its USB
configuration descriptor and when the USB port to which the device is connected supports
remote wake-up the device can wake up the PC. The driver supports wake-up on magic
packet and wake-up on network cable connect. The user can modify the behavior of the
network adapter with the Power Management tab in the properties dialog of the driver.
вЂў VLAN Support. The driver supports Virtual LANвЂ™s. In the advanced property dialog page
the user can select a VLAN number. The VLAN number 0 means the feature is turned off
and the driver will send untagged packets and accept all packets. If a VLAN number greater
than 0 is selected, the driver will accept packets with the correct VLAN tag or no VLAN
tag. It will send packets with the correct VLAN tag.
вЂў MAC Address. By default, the driver uses the MAC address reported by the device. If the
device cannot provide a MAC address, the driver can use a MAC address defined in the INF
file. The user can assign the current MAC address in the advanced property page dialog.
вЂў IP Address. The IP address of the adapter can be assigned via DHCP, Auto-IP or manually.
вЂў Multiple USB Interfaces. The EEM class driver can be used with devices that implement
multiple USB interfaces. A separate network adapter instance will be created for each EEM
interface. Thesycon offers a multi-interface driver that can be used to build an individual
device node for each interface. For more information, check out http://www.thesycon.de
USB Multi Interface Driver.
вЂў Multiple USB Devices. Multiple USB devices can be controlled by the driver at the same
time.
вЂў Customizing. The CDC/EEM allows vendor- and product-specific adaptations.
12
USB CDC/EEM Class Driver Reference Manual
2 Overview
вЂў Installation/Uninstallation. For customized driver installations Thesycon offers the PnP
Driver Installer. Additional information are available at
http://www.thesycon.de/pnpinstaller.
вЂў WHQL Certification. The driver conforms to MicrosoftвЂ™s Windows Driver Model (WDM)
and NDIS, and it can be certified by Windows Hardware Quality Labs (WHQL) for all
current 32-bit and 64-bit operating systems. The WHQL test requires a lot of features inside
the device. Please check the most current requirements list from Microsoft. The HCK tests
expect that the device implements a physical Ethernet connection to a service PC that allows
the exchange of network packets. If your device has a different purpose or architecture, you
must discuss with Microsoft whether a WHQL certification is possible.
The NDIS layer on Vista SP2 has a bug that requires a manual exception from Microsoft to
ignore the failure of the PnP test.
USB CDC/EEM Class Driver Reference Manual
13
2 Overview
2.3 USB 2.0 support
The CDC/EEM device driver supports USB 2.0 and the Enhanced Host Controller on
Windows XP, Windows Vista, Windows 7 and Windows 8. However, CDC/EEM must be used
on top of the driver stack that is provided by Microsoft. Thesycon does not guarantee that the
CDC/EEM driver works in conjunction with USB driver stacks provided by third parties.
Third-party drivers are available for USB 2.0 host controllers from NEC, INTEL or VIA. Because the Enhanced Host Controller hardware interface is standardized to the EHCI specification,
the USB 2.0 drivers provided by Microsoft can be used with host controllers from any vendor.
However, the user must ensure that these drivers are installed.
2.4 USB 3.0 Support
Currently, more and more computers with Extended (USB 3.0) Host Controllers (xHC) are coming
onto the market. The xHC handles full and high speed data traffic. If a customer connects your
CDC/EEM device to a USB 3.0 host controller connector, it will run with an xHC and the installed
bus driver stack.
Microsoft has released the USB 3.0 bus driver for xHCs with Windows 8. Other vendors of USB
3.0 controllers provide their own driver stacks for older operating systems. It is nearly impossible
to test all of these controllers and versions of USB driver stacks.
Thesycon tests using the Renesas and Intel controllers with the vendor-provided driver stacks on
Windows 7 and the Microsoft-provided driver stack on Windows 8. The CDC/EEM driver can
also work with USB 3.0 controllers from other vendors, but Thesycon cannot give a warranty that
this will work without problems.
Today, most devices with a USB 3.0 super speed interface are mass storage devices. They use
system-provided drivers. On the market other devices with a USB 3.0 interface are rare. For that
reason it is difficult to make comprehensive tests with USB 3.0 devices at this moment in time.
The CDC/EEM driver is designed to support USB 3.0 devices with super speed, however because
of the test situation, Thesycon cannot give warranty that it works in every case. If you intend to
plan a project using a USB 3.0 device, please contact Thesycon (www.thesycon.de).
2.5 Known Issues
2.5.1 Driver is not loaded after disconnect
This problem occurs on Windows 7, Windows Vista and Windows XP 32/64 bit. When the device
is disconnected from the USB bus and reconnected after a short time period, the driver is not
loaded by the system. In the device manager, the device node is marked with error code 31 and
the network interface is not available. Debug output from the driver shows clearly that the driver
is stopped and unloaded when the device is removed. However, it is not loaded when the device is
re-connected in the problem situation.
This seems to be a problem in the Microsoft NDIS driver framework that it is not able to handle a
device add event correctly when the device remove operation is not yet completed.
A workaround for this problem is to delay the soft connect in the device for some seconds. Normally the device connects to the USB bus by turning on the connect resistor as soon as it is ready
14
USB CDC/EEM Class Driver Reference Manual
2 Overview
to handle USB requests. The workaround means that the device delays this connect operation. It is
difficult to determine exactly how long the device must be disconnected to avoid the problem. The
time period depends on the host hardware and on the load situation when the device is removed,
as well as on the software that is installed on the PC. The error is also resolved when the device is
removed and re-connected to the PC a second time.
USB CDC/EEM Class Driver Reference Manual
15
3 Architecture
3 Architecture
Figure 1 shows the USB driver stack that is part of the Windows operating system. All drivers are
embedded within the WDM layered architecture.
вњ§в�…вњ„вњЊвњ©вњ«вњЄвњ–вњў в�›вњвњ¬вњ®вњ†вњџвњ„вњ¦вњў вњЇ
вњ°вњњВ вњ‚вњ±вњІвњ вњЎвњ™ вњ¤ вњ„вњ¦в�ћвњџвњі вњЇв�Ћвњ„вњњвњі вњ вњњвњґ
вњ§в–Івњ¤ в�ћв�Ћвњ¶вњ·в�›вњвњ¬вњ®вњ†
в–јвњљв—†вњњв—†вњ·вњ™ вњ¤ вњ вњџвњ›вњЎвњі вњ¤ в�›вњЊв�ћ
вќ™вњЊвќљвќЉвќЇ вќ±вњ–вќІв�Ћвќі вќЁвњ¦вќ©вњ–вќ¬вњЊвќ вќЄвњвќ«вќЏвќґвњ·вќІвњџвќµвќЉвќЁвќЌвќљвњвќЇ вќЄвњвќ«вќ„вќљвњвќЇ вќµвњвќ›
вњ§вњµвњ¤ в�ћв�Ћвњ¶вњ·в�›вњвњ¬вњёвњ†вњёВ вќ–вњЌвњљвњ±вњЊвњ“в——ВЂ вњ±вњІвњ»вќ–вњі вњ›вњњвњ вњЎвќ�
вќ™вњЊвќљвњвќЇ вќ±вњ–вќІв�Ћвќі вќЁвњ’вќњвњ¦вќі вќќ вќћвќЏвќљв�Ћвќівњќвќ вќЎв—ЏвќЇ вќљв�Ћвќі вќў вќЈвњвќµв—Џвќљвњёвќ¤ вќ™вќ–вќњвњђвќ вќґвњќвќҐ
В вњ‚вњЃв�Ћвњ„вњќвњ†вњџвњћвњЎвњ вњџв�›вњЊв�ћвњЋвњЌвњ‘вњЏвњ’вњЌвњ‚вњ“вњ•вњ”вњ–вњ”вњ–вњ—вњ�вњЌвњљвњ™ вњ›вњњвњ†вњџвњ†вњЋвњЏвњЈвњў вњ¤ вњҐвњЎвњ„вњ¦вњў
вњ§вњµвњ¤ в�ћв�Ћвњ¶вњ·в�›вњвњ¬вњёвњ†вњєвњ№вњ’вњ»вњ’вњЄвњјвњЄвњ‚вњЅв�Ћвњ†вњєвњЏвњЈвњў вњ¤ вњҐв�Ћвњ„вњ¦вњў
вњѕвњљвњї вќЂвќ‚вќЃвќ„вќѓвќ‚вќ…вњ·вќ†вќ€вќ‡вќЉвќ‰в—Џвќ‹ вќЂвќЌвќ‰вќЏв– вњ•вќ‘вќ€вќѓвќ„вќЃвќЌвќ‰
вњ№вњ’вњ»вќ¦вњЄв™ вќ§вњ’в�›вњњвњ†вњвњівњЊвњЌвњЈв�›вњЊв�ћв�Ћвњі вњў в�›вњЊвњ™ вњ™ вњ„вњЊвњў
Figure 1: USB CDC/EEM Driver Stack
The following modules are shown in Figure 1:
вЂў USB Host Controller is the hardware component that controls the Universal Serial Bus. It
also contains the USB Root Hub. Depending on your PC, the device can be connected to
an Open Host Controller (OHC), a Universal Host Controller (UHC), an Enhanced Host
Controller (EHC) or an eXtensible Host Controller (xHC).
вЂў Windows USB Bus Driver consists of USB Bus Driver, USB Hub driver and the USB Host
Controller driver. These are Windows Kernel Mode drivers. The drivers are provided by
Microsoft or the vendor of the USB host controller.
вЂў Thesycon CDC/EEM Class Driver is also a Windows Kernel Mode driver developed by
Thesycon GmbH. This driver implements the USB CDC/EEM protocol and establishes a
network interface.
вЂў The interface between the Thesycon CDC/EEM Class Driver and the Windows TCP/IP
Stack is described by the Network Driver Interface (NDIS).
вЂў The Windows TCP/IP Stack is provided by Microsoft. It contains protocol drivers for several network protocols (for example IPv4 and IPv6). This stack handles the communication
with User Mode applications.
вЂў As interface between User Mode applications and the Windows TCP/IP Stack can be used by
several Network APIs, Sockets etc. These are described in the MSDN Library (networking
section).
вЂў User Mode applications, for example web browsers or FTP clients etc., use the Network
APIs, Sockets etc. to communicate over the network interface. Several applications can
communicate over the network interface at the same time.
USB CDC/EEM Class Driver Reference Manual
17
3 Architecture
The driver stack that arises on a given PC depends on the available host controllers and the way
the device is connected to the PC. Each different driver stack can behave different related to the
timing of the data packets.
3.1 Special Properties of the Driver
3.1.1 NDIS Model
Microsoft supports different versions of the NDIS model. We provide a driver for the NDIS 5.1
model that is used on Windows XP and Vista, and a driver that works with the NDIS 6.2 model
used with Windows 7 and later. The INF file is designed in such a way that the correct driver for
an operating system is always installed. The driver that implements the NDIS 5.1 model has the
marker "51" in the name. The driver for the NDIS 6.2 model uses "62".
3.1.2 Surprise Removal Dialog
Windows can show plug and play devices on the PnP card in the Systray, and can complain if such
devices are removed from the system without being stopped. The driver suppresses this entry in
the Systray. The device can be removed from the PC without any preparation.
3.1.3 Power Management
The driver supports the requests for power management. For this reason the adapter is not stopped
if the PC enters standby, sleep or hibernate. An advantage of this is that a device with AutoIP
address negotiation must not restart the negotiation after the power down state of the PC. It is not
recommended to use AutoIP because it takes a long time before Windows can assign a valid IP
address.
3.1.4 Remote Wakeup
The driver supports remote wake-up on "Magic Packet" and on "Link Up". The features must be
enabled in the INF file and must be supported by the device.
3.1.5 VLAN
The driver supports VLAN. The adapter can be configured to add one VLAN ID to the network
traffic. The driver does not support multiplexing between different VLAN networks. The feature
can be enabled with INF file parameters.
3.1.6 MAC Address
The driver determines the valid network address (MAC Address) in the following way:
1. The driver reads the network address from the device. If this fails
2. The driver reads the network address from the registry. If this fails
18
USB CDC/EEM Class Driver Reference Manual
3 Architecture
3. The driver has a built-in MAC address with the value AE:DE:48:02:01:00. This address has
set the local bit and is not neccesarily unique.
3.1.7 Statistic Counters
The driver requests the statistic counters from the device when the device supports it. To save
bandwidth, the request period can be defined in the INF file. Between the statistic requests, the
driver reports cached values.
3.1.8 Multiple interfaces on one device
The CDC/EEM driver can be used with devices that implement multiple USB interfaces. In this
case, a multi-interface driver is required. This driver splits the interfaces to separate device nodes.
A new driver stack can then be installed on each device node.
The system-provided multi-interface driver used before Windows XP SP3 cannot be used together
with the CDC/EEM driver. The reason is that this CDC/EEM interface consists of two USB
interfaces, and these two interfaces must be mapped to one device node. The system-supplied
multi-interface driver is not able to detect USB interfaces that belong together. Later versions of
the system-provided MI driver can handle the IAD. It is recommended that you add an IAD to
your configuration descriptor.
Thesycon provides a special multi-interface driver that can handle this problem in a correct way.
This driver is required if you have to support systems before Windows XP SP3. This driver can be
licensed separately.
USB CDC/EEM Class Driver Reference Manual
19
4 Driver Customization
4 Driver Customization
4.1 Overview
The CDC/EEM driver supports numerous features that enable a licensee to create a customized
device driver package. A driver package which is shipped to end users must be customized.
This is required in order to avoid potential conflicts with other products from other vendors that
are also using this driver. See also section 4.2 for a discussion of the reasons why a full driver
customization is absolutely required.
Customization includes:
вЂў Modification of file names of all driver executables,
вЂў Modification of text strings shown in the Windows user interface,
вЂў Definition of unique software interface identifiers and
вЂў Adaptation of driver behavior for a specific device.
4.2 Reason for Driver Customization
ThesyconвЂ™s CDC/EEM driver is generic with respect to concrete products. The driver can be used
(and shipped together) with many different products from various vendors. All generic drivers
must be customized. Customization includes modification of device identifiers, choice of unique
file names, assignment of unique identifiers (GUIDs) and modification of display names.
If customization is not properly completed, the following situation can occur in the field:
1. User buys product A and installs it. Product A works.
2. Same user buys product B (from another vendor) and installs it. B ships with the same
(non-customized) driver as A.
This situation results in a couple of potential problems:
вЂў B driver .sys files overwrite A driver .sys files which reside in the Windows drivers directory.
This can cause product A to stop working e.g. because a different driver version is now
loaded.
вЂў Product A control panel detects a product B device and tries to work with it.
вЂў Product B control panel detects a product A device and tries to work with it.
вЂў Uninstall of product A removes .sys files (and possibly other files) which causes product B
to become non-functional.
вЂў Uninstall of product B removes .sys files (and possibly other files) which causes product A
to become non-functional.
Important: To ship the driver to end users, a customized driver package must be created. Never
ship the original driver package provided by Thesycon to end user.
USB CDC/EEM Class Driver Reference Manual
21
4 Driver Customization
4.3 Digital Signature for Windows Vista, Windows 7, Windows 8 and Windows 8.1
Windows Vista and later Windows versions have a new feature to verify a vendor of a software
component. The vendor can add a digital signature to a software component to identify itself.
This signature grants that the software was signed by the vendor and that the software was not
modified after it was signed. Please note that it is not possible to install a driver without a digital
signature on the 64-bit version of Windows Vista or higher. For background information about
code signing, please refer to the document "Kernel-Mode Code Signing Walkthrough" available
on the Microsoft web site.
To add a digital signature to a software component, the vendor must own a certificate that supports
the Microsoft Authenticode technology (sometimes called Microsoft Authenticode Digital ID).
Such a certificate can be purchased from several certification authorities (CA), including Symantec
(formerly Verisign). For details you may refer to
http://www.symantec.com/verisign/code-signing/microsoft-authenticode
Alternatively, search the Web for for
"VeriSign Code Signing Certificates for Microsoft Authenticode".
4.3.1 Using the Driver without Code Signing Certificate
If you donвЂ™t own a code signing certificate you can still create a customized driver package as
described in sections 4.4 and 4.5 below. However, during driver installation on the target system,
Windows will show a warning message stating that the vendor of the driver software cannot be
verified, see Figure 2. The user needs to confirm this warning in order to continue with driver
installation. Windows shows this warning because the .cat files in the driver package are not
digitally signed.
Figure 2: Windows security warning shown if .cat files are not digitally signed
The .sys files included in the driver package are signed with ThesyconвЂ™s certificate. If a user
inspects the file properties of the .sys file (or driver details in Device Manager) then he/she will
find out that the driver is provided by Thesycon.
For instructions on how to proceed without a code signing certificate, refer to specific comments
given in the subsequent sections.
Drivers that does not have a digital signature cannot be loaded on the 64-bit variants of Windows 7
and Windows 8. Windows 7 will load the driver if the .sys file has a digital signature, while
Windows 8 requires a valid digital signature on the .cat file.
22
USB CDC/EEM Class Driver Reference Manual
4 Driver Customization
On both systems, an unsigned driver can be loaded if the "Driver Signature Enforcement" is disabled in the "Advanced Boot Options". On Windows 7, these boot options can be accessed by
pressing F8 during the boot process. On Windows 8, a special boot menu can be started with the
command line "Shutdown.exe /r /o" or by holding the Shift Key while pressing Restart. For more
details see the Windows documentation.
Note: The driver signing enforcement is turned off only for one boot process. This method should
be used only on development PCs.
4.4 Preparing Driver Package Builder
Thesycon provides a set of batch scripts and tools that generate driver packages and all required
customization files automatically. This tool set is called the Driver Package Builder.
Before the scripts can be used, the steps described in the following subsections must be executed
on the machine on which the Driver Package Builder will run.
4.4.1 Install SignTools
The following Microsoft tools are required:
вЂў signtools.exe (part of WDK)
вЂў inf2cat.exe (part of WDK)
вЂў INF checker (part of WDK)
For your convenience, Thesycon has collected the required tools in a SignTools package installer.
This driver package requires SignTools version 1.5.0. To get a free copy of this SignTools installer,
contact Thesycon.
To install the SignTools package, run SignTools_v1.5.0.exe.
NOTE: If you donвЂ™t own a code signing certificate (see 4.3.1 above) then you still need to execute
this step. The SignTools package is required to create the .cat files.
4.4.2 Check your Code Signing Certificate
NOTE: If you donвЂ™t own a code signing certificate (see 4.3.1 above) then you can skip this step.
The certificate to be used for code signing needs to be present in the certificate store of the build
machine. For information on how to get the certificate and how to import it into the certificate
store, please refer to instructions published by your certificate provider.
Before you continue, you should check if the certificate is present in the Personal folder of the
certificate store of the machine in which you want to run Driver Package Builder. To do this, click
Start - Run and enter certmgr.msc. This launches the Certificates Microsoft Management
Console. The Personal folder should contain your certificate and should look similar to figure 3.
To verify that the certificate is valid for code signing, double-click on the certificate to open the
Details view. The Certificate Information dialog should look as shown in figure 4. For code
signing, the private key that corresponds to the certificate must be available. This is indicated by
USB CDC/EEM Class Driver Reference Manual
23
4 Driver Customization
Figure 3: Certificates Microsoft Management Console
the key icon at the bottom of the General page and the statement "You have a private key that
corresponds to this certificate." If the key icon is missing, only the public key of the certificate is
installed and code signing will not be possible.
Figure 4: Certificate Information
4.4.3 Configure Certificate Variables
NOTE: If you donвЂ™t own a code signing certificate (see 4.3.1 above) then you can skip this step.
If no certificate is available, VENDOR_CERTIFICATE, VENDOR_CROSS_CERTIFICATE and
SIGNTOOL_TIMESTAMP_URL must not be defined, this is the default in
set_vendor_certificate.cmd.
If you own a code signing certificate, edit the set_vendor_certificate.cmd script contained in the signing subdirectory of the install folder. This script must refer to your certificate
24
USB CDC/EEM Class Driver Reference Manual
4 Driver Customization
in the certificate store described in the previous step. In set_vendor_certificate.cmd,
set the variables described below according to your certificate. See also the comments and instructions given within the script itself. Note that alternatively you can add the variables to your build
machineвЂ™s environment.
вЂў VENDOR_CERTIFICATE
This variable needs to be set to your certificateвЂ™s name exactly as shown in certmgr.msc.
Do not surround the string with quotation marks. If your certificate name includes special
chars, precede each of them with an escape character (^).
Example:
set VENDOR_CERTIFICATE=MyCompany Ltd.
вЂў VENDOR_CROSS_CERTIFICATE
This variable specifies the cross certificate that should be used. The cross certificate establishes a trust relationship between Microsoft and your certificate issuer. For latest information on cross certificates, see the article "Cross-Certificates for Kernel Mode Code Signing"
in the MSDN library:
http://msdn.microsoft.com/
en-us/library/windows/hardware/gg487315.aspx
Alternatively, ask your certificate provider which cross certificate is to be used.
Example:
set VENDOR_CROSS_CERTIFICATE=c:\MyProject\Signing\
VeriSign-Class-3-Public-Primary-Certification-Authority-G5.cer
вЂў SIGNTOOL_TIMESTAMP_URL
This variable specifies a trusted time stamp server to be used when the signature is created. Note that a signature should always be timestamped. In case of Symantec (formerly
VeriSign), you can keep the default shown in set_vendor_certificate.cmd. If
you are using a different certificate provider, refer to the documentation published by this
provider.
Example:
set SIGNTOOL_TIMESTAMP_URL=http://timestamp.verisign.com/
scripts/timestamp.dll
4.4.4 Prepare for GUID Generation
Various Globally Unique Identifiers (GUID) are needed for the customization procedure. A GUID
can be created easily by using MicrosoftвЂ™s guidgen.exe utility. This utility is part of the Microsoft Visual Studio 2005, Visual Studio 2008 and Visual Studio 2012 distribution. Note that it
is not included in Visual Studio 2010.
The guidgen.exe utility can also be downloaded from this URL:
http://www.microsoft.com/
download/en/details.aspx?displaylang=en\&id=17252
USB CDC/EEM Class Driver Reference Manual
25
4 Driver Customization
4.5 Using Driver Package Builder
The Driver Package Builder batch scripts are located in the DriverPackageBuilder subdirectory of the driver kit. To create your own customized driver package, please follow the steps
described in the following subsections.
NOTE: These steps are mandatory and must be executed to avoid problems in the field.
4.5.1 Customize your Driver Package
The driver package is configured by means of a set of variables defined in setvars.cmd. To
configure your driver package, edit this file.
The following step-by-step procedure includes the major customizations steps. Make sure that
you check the value of each variable contained in setvars.cmd. For a detailed description of
each variable, refer to section 4.6.
1. Set vendor and product strings
Adapt the following strings to match your company and product:
VENDOR_NAME=
PRODUCT_NAME=
DRIVER_NAME_BASE=
2. Adapt USB VIDs and PIDs
Each product (device model) is unambiguously identified by its USB vendor ID (VID)
and USB product ID (PID). The setvars.cmd script allows you to define up to 16 devices which will all be supported by the same driver package. Set one or more of the
INF_VID_PID_xx variables to match with your deviceвЂ™s VID(s) and PID(s). Be careful
to get the special format of the INF_VID_PID_xx string right. See also the comments
and examples within setvars.cmd.
Set INF_VID_PID_xx_DESCRIPTION to your productвЂ™s name. This string will be
shown in Device Manager as a product description.
Clear all unused INF_VID_PID_xx variables, e.g.:
set INF_VID_PID_05=
set INF_VID_PID_05_DESCRIPTION=
3. Driver Parameter Configuration
The file driver_parameters.inc contains the driver parameters. You can modify the
parameters to fit the driver behavior to your device. See section 4.7 for details.
4.5.2 Build your Driver Package
Open a Windows console window (cmd.exe) in the DriverPackageBuilder directory. From
the command line, run the create_drvpackages.cmd script. Make sure your PC is connected to the Internet to get the certified time stamp from your certificate provider. This ensures
that your digitally signed driver package is still valid after your signing key has been expired.
26
USB CDC/EEM Class Driver Reference Manual
4 Driver Customization
Your customized driver package will be created under the driver_package subdirectory.
NOTE: If you donвЂ™t own a code signing certificate, the .sys files will be signed with ThesyconвЂ™s
certificate and the .cat files will not be digitally signed. This leads to a different behavior during
driver installation. See 4.3.1 for more details. The unsigned driver package will be created under
the driver_package_unsigned subdirectory.
It is strongly recommended to check the .inf files of the created driver package using the script
check_inf_files.cmd. The script opens a .html file with the results of the check.
To create different packages, make a copy of the folder DriverPackageBuilder and configure the second driver package in the copied folder.
Modifications to the driver package make the digital signature invalid. When manual changes to
the INF file are required the digital signature can be updated with the script
update_signature.cmd. Keep in mind that the script
create_driverpackages.cmd overwrites the modified driver package without warning.
The scripts create_driverpackages.cmd and update_signature.cmd can be called
with the command line parameter no_sys_signing. When this parameter is used, the .sys
files are not digitally signed. This can be helpful when the driver package should be used for the
WHQL testing.
4.6 Customization Parameter Reference
4.6.1 VENDOR_NAME
The vendor of the driver package. This string is used as provider and manufacturer string in (.inf
file).
4.6.2 PRODUCT_NAME
The name of the product that uses the driver package. It is used to generate the Disk Name string
in the INF file.
4.6.3 DRIVER_NAME_BASE
The common part of the name of the driver package files. This name should be globally unique.
You should add an abbreviation of your company name to the driver base name. This string must
not include spaces or special characters.
4.6.4 INF_VID_PID_[01..16]
USB Vendor ID(s) and Product ID(s) of the USB devices (models) that are supported by the driver
package.
Format: VID_xxxx&PID_yyyy or VID_xxxx&PID_yyyy&MI_zz
xxxx specifies the VID in hex format, yyyy specifies the PID in hex format. If the driver is installed
on a multi-interface architecture, zz identifies the interface number.
USB CDC/EEM Class Driver Reference Manual
27
4 Driver Customization
4.6.5 INF_VID_PID_[01..16]_DESCRIPTION
Display name of the respective device model. This name is displayed in Windows Device Manager. A display name can be specified for each VID/PID pair.
4.7 Customization Default Driver Settings
The INF file specifies some settings that define the default behavior of the driver. The settings can
be modified in the file driver_parameters.inc. These settings are defined in the following
section.
4.7.1 RxBuffers
This parameter defines number of read buffers. Some of the read buffers are submitted to the host
controller. The other buffers can hold received data while these data are processed by the protocol
drivers. The default value is 40.
4.7.2 RxBuffersSubmitted
This parameter describes the number of buffers that are submitted to the bus driver. The default
value is 10. It can cause a high CPU load if a lot of Rx buffers are submitted to the host controller.
4.7.3 TxBuffers
This parameter defines number of write buffers. The default value is 16. All these buffers can be
submitted to the host controller. The driver can store additional Tx data in a queue that maintains
NDIS data structures.
4.7.4 DefaultMediaState
If this parameter is 1, the driver reports the media state as connected. The PC can send immediate
requests to the device. If this parameter is set to 0, the driver waits on a notification from the
device that the media state is changed to connected. Default is 0.
4.7.5 MediaStateAfterPowerDown
This parameter defines the media connection state after power down. When the device reports the
media state after each power down operation the value can be set to 0. In this case the driver does
not report the media state to the NDIS layer. When the parameter is set to 1, the driver reports the
media state as connected when the power state is switched to working. When the parameter is set
to 2, the driver reports the media state as disconnected to the NDIS layer. If the media state is not
reported correctly to the NDIS layer after power down, the adapter is not working.
28
USB CDC/EEM Class Driver Reference Manual
4 Driver Customization
4.7.6 DefaultXmitLinkSpeed
This parameter can be used to provide a default transmit link speed. It seems that some protocol
drivers, for example the PPPoE, request the link speed even if the adapter is not connected. The
value is measured in bits per second.
4.7.7 DefaultRcvLinkSpeed
This parameter can be used to provide a default receive link speed. It seems that some protocol
drivers, for example the PPPoE, request the link speed even if the adapter is not connected. The
value is measured in bits per second.
4.7.8 MaxXmitLinkSpeed
This parameter defines the maximum transmit link speed. The value is measured in bits per second.
4.7.9 MaxRcvLinkSpeed
This parameter defines the maximum receive link speed. The value is measured in bits per second.
4.7.10 OneByteTermination
If this parameter is 1, the PC driver terminates a packet that can be divided by the FIFO size
without rest with an additional byte. If this parameter is zero, the driver terminates such a packet
with a zero length packet. Set this parameter to 1 if your hardware cannot handle zero length
packets. The default value is 0. Note: Linux use the same algorithm.
4.7.11 ConfigurationIndex
Is the zero-based USB configuration index that is activated by the driver. Some Linux gadget
implementations exposes the CDC/EEM interface on index 1.
4.7.12 SendClearEpHaltOnStart
If this value is not 0, the driver sends the standard command clear feature endpoint stall on each
data pipe before the data transfer is started.
4.7.13 StatisticsUpdateInterval
This value is used to update Ethernet statistics if the device supports it. To save bandwidth, the
driver requests only the parameters that are requested by the PC.
4.7.14 VendorDescription
This is the vendor description reported to the NDIS layer.
USB CDC/EEM Class Driver Reference Manual
29
4 Driver Customization
4.7.15 TxTimeout
TxTimeout is the period in milliseconds in which the driver expects that at least one TX packet
has been transferred to the adapter. When the timeout expires the NDIS layer forces an adapter
reset.
4.7.16 CapWakeOnMagicPacket
Set this parameter to 1 if the device can wake the system when the adapter receives a Magic Packet.
The USB interface has to support remote wakeup to use this feature.
4.7.17 CapWakeOnLinkUp
Set this parameter to 1 if the device can wake the system when the network link comes up. This
happens when the network cable is plugged in or when the router is turned on. The USB interface
has to support remote wakeup to use this feature. The adapter must also support Wake on Magic
Packet.
30
USB CDC/EEM Class Driver Reference Manual
4 Driver Customization
4.8 Advanced Dialog Parameters
The following parameter blocks can be used to allow the user the modification of configuration
parameters. These parameters are shown in the advanced dialog of the driver property dialog.
; VLAN ID
HKR, Ndi\params\VlanID,
HKR, Ndi\params\VlanID,
HKR, Ndi\params\VlanID,
HKR, Ndi\params\VlanID,
HKR, Ndi\params\VlanID,
HKR, Ndi\params\VlanID,
HKR, Ndi\params\VlanID,
ParamDesc,
default,
type,
min,
max,
step,
base,
0,
0,
0,
0,
0,
0,
0,
"VLAN ID"
"0"
"long"
"0"
"4094"
"1"
"10"
;PriorityVLANTag
HKR, Ndi\params\*PriorityVLANTag,
HKR, Ndi\params\*PriorityVLANTag,
HKR, Ndi\params\*PriorityVLANTag,
HKR, Ndi\params\*PriorityVLANTag\enum,
HKR, Ndi\params\*PriorityVLANTag\enum,
HKR, Ndi\params\*PriorityVLANTag\enum,
HKR, Ndi\params\*PriorityVLANTag\enum,
ParamDesc,
default,
type,
"0",
"1",
"2",
"3",
0,
0,
0,
0,
0,
0,
0,
"Priority and Vlan"
"0"
"enum"
"Disabled"
"Packet priority enabled"
"VLAN Enabled"
"Packet priority and VLAN enabled"
; this block is not used when CapWakeOnMagicPacket is
;HKR, Ndi\params\*WakeOnMagicPacket,
ParamDesc,0,
;HKR, Ndi\params\*WakeOnMagicPacket,
default, 0,
;HKR, Ndi\params\*WakeOnMagicPacket,
type,
0,
;HKR, Ndi\params\*WakeOnMagicPacket\enum,"0",
0,
;HKR, Ndi\params\*WakeOnMagicPacket\enum,"1",
0,
0
"Wake on Magic Packet"
"1"
"enum"
"Disabled"
"Enabled"
; this block is not used when CapWakeOnLinkUp is 0
;HKR, Ndi\params\WakeOnLinkUp,
ParamDesc,0,
;HKR, Ndi\params\WakeOnLinkUp,
default, 0,
;HKR, Ndi\params\WakeOnLinkUp,
type,
0,
;HKR, Ndi\params\WakeOnLinkUp\enum,
"0",
0,
;HKR, Ndi\params\WakeOnLinkUp\enum,
"1",
0,
"Wake on Link Up"
"1"
"enum"
"Disabled"
"Enabled"
4.8.1 VLAN ID
If this parameter block is enabled, the user can set a VLAN ID for the adapter. The VLAN ID
identifies a virtual network on the LAN. The VLAN ID is added to the MAC header and changes
the layout of the Ethernet frames. This parameter is used when the setting PriorityVLANTag
enables VLAN. Remove this block if not supported by the device.
4.8.2 PriorityVLANTag
With this parameter the user determines whether the driver sends the VLAN tag with VLAN and/or
priority information. Remove this block if not supported by the device.
4.8.3 WakeOnMagicPacket
This parameter can be used to disable the Wake on Magic Packet feature when supported by the
device. If this feature is not supported, remove this block.
USB CDC/EEM Class Driver Reference Manual
31
4 Driver Customization
4.8.4 WakeOnLinkUp
This parameter can be used to disable the Wake on Link Up feature when supported by the device.
If this feature is not supported, remove this block.
32
USB CDC/EEM Class Driver Reference Manual
5 Driver Installation and Uninstallation
5 Driver Installation and Uninstallation
This section discusses topics relating to the installation and uninstallation of the CDC/EEM device
driver.
5.1 Driver Installation for Developers
This section describes some methods of how developers can install and un-install the CDC/EEM
driver on a PC.
5.1.1 Installing CDC/EEM Driver Manually
Only developers should install the driver manually.
In order to install the CDC/EEM driver manually you must prepare an INF file that matches your
device (see chapter 4).
The steps required to install the driver are described below.
вЂў Copy the .inf, .sys and .cat files that are required for the operating system in use to the hard
disk. Use a folder like
c:\program files\<Vendor>\<Product>\<Version>\drivers.
Do not copy the files into system folders.
If you install the driver files directly from a removable medium, Windows XP will ask you
to insert the medium again on the next installation process.
вЂў Connect your USB device to the system. After the device has been plugged in, Windows
launches the New Hardware Wizard and prompts you for a device driver. On Windows
Vista and later, the system will show you a small notification to say that the driver was not
installed correctly. In this case, you have to open the device manager manually and update
the driver for your device.
Provide the New Hardware Wizard with the path of your installation files (e.g. cdceem.inf
and cdceem.sys). Complete the wizard by following the instructions shown on screen. If
the INF file matches your device, the driver should be installed successfully.
вЂў If the operating system contains a driver that is suitable for your device, the system will not
launch the New Hardware Wizard when the device is plugged in. Instead of that, a systemprovided device driver will be installed silently. The operating system does not ask for a
driver because it finds a matching entry for the device in its internal INF file data base.
You must use the Device Manager to install the driver for a device for which a driver is
already running. To start the Device Manager, right-click on the "My Computer" icon and
choose Properties. In the Device Manager, right-click on your device and choose Properties.
On the property page that pops up, choose Driver and click the button labeled "Update
Driver". An Upgrade Device Driver Wizard is started that is similar to the New Hardware
Wizard described above. Provide the wizard with the location of your installation files and
complete driver installation by following the instructions shown on screen. To make sure
the system installs the correct driver, donвЂ™t search for the best driver. Select it from a list
and use the button "Have Disk" to browse to the file location.
USB CDC/EEM Class Driver Reference Manual
33
5 Driver Installation and Uninstallation
вЂў After the driver installation has been successfully completed, your device should be shown
in the Device Manager in the section Network Adapters. You may use the Properties dialog
box of that entry to verify the driver is installed and running.
вЂў To verify that the driver is working properly with your device, you can check the adapter
with the command line tool ipconfig. Depending on the device capabilities, the adapter
gets an IP address from DHCP or Auto IP. You can assign a static IP address in the network
dialog. You can try to use the command line tool ping to get contact to your device.
Consider fire wall settings on the PC.
5.1.2 Uninstalling CDC/EEM manually
Only developers should uninstall the driver manually. If an important system driver is removed,
the system can become unusable.
To uninstall the device driver for a given device, use the Device Manager. The Device Manager
can be accessed by right-clicking the "My Computer" icon on the desktop, choosing "Properties"
from the context menu and then opening the Device Manager window. In the Device Manager
window, double-click on the entry for the device and choose the property page labeled "Driver".
There are two options to uninstall the device driver:
вЂў Remove the selected device from the system by clicking the button "Uninstall". The operating system will re-install a driver the next time the device is connected or the system is
rebooted.
вЂў Install a new driver for the selected device by clicking the button "Update Driver". The
operating system launches the Upgrade Device Driver Wizard which searches for driver
files or lets you select a driver.
In order to avoid automatic and silent re-installation of the driver by the operating system, it is
necessary to remove the driver installation from the system.
On Windows Vista and higher, the complete driver package, with .sys, .inf and .cat files, is stored
in the driver store. To remove it from the driver store, the dialog that is shown during the uninstallation allows the deletion of drivers in the store. On Windows XP, the .inf file must be removed
manually.
During driver installation, Windows XP stores a copy of the INF file in its internal INF file data
base located in %WINDIR%\INF\. The name of the INF file is changed before it is stored in the
database. On Windows XP, the INF file is stored as oemX.inf, where X is a decimal number.
The best way to find the correct INF file is to do a search for some significant string in all the
INF files in the directory %WINDIR%\INF\ and its subdirectories. Note that on Windows XP,
the %WINDIR%\INF\ directory has the Hidden attribute by default. Therefore, by default, the
directory is not shown in Windows Explorer.
On Windows Vista and higher, the .cat file is stored in an additional place. If you install the
same driver a second time, the system behavior may be different, because the system knows the
driver and does not warn the user for a non-certified driver. Furthermore, the digital signature
can be stored in the certificate manager under Trusted Publishers. This happens if the user selects
34
USB CDC/EEM Class Driver Reference Manual
5 Driver Installation and Uninstallation
"always trust this vendor" during the installation process. If the certificate is stored there, all
digitally signed drivers can be installed in the same way as with a WHQL signature.
Once you have located the INF file, delete it. This will prevent Windows from reinstalling the
driver. Instead, the New Hardware Wizard will be launched and you will be asked for a driver.
5.2 Installing CDC/EEM driver for End Users
This section describes how the driver should be installed on a PC by the end user of the product.
5.2.1 Installing CDC/EEM driver with the PnP Driver Installer
Thesycon provides a PnP Driver Installer Package that can be used to install kernel mode drivers
in a convenient and reliable way. This installer is not part of this package. It can be downloaded
separately under the following link: http://www.thesycon.de/pnpinstaller.
The installation program can be run in an interactive mode with a graphical user interface or can
be run in a command line mode. The command line mode is designed to integrate the driver
installer into other installation programs. The GUI mode guides the user through the installation.
It supports different languages.
The driver installer package can be customized. A detailed description of the customization options is part of the reference documentation.
The PnP Driver Installer Package can handle the driver installation and uninstallation in different
situations:
вЂў During first time installation the driver is pre-installed in the system. In this step, the user
needs administrator privileges. If the driver is certified, the pre-installation of the driver is
performed silently. This means the hardware wizard is not launched and the system does not
show a warning box for non-certified software. If the device is connected to the PC during
installation, the correct driver software is installed immediately. If a device is connected to
the PC later, the certified driver is installed silently. At the point of time where the device is
connected to the PC, no administrator privileges are required.
вЂў The installer can perform a driver update. Old drivers and driver instances are removed from
the system regardless of whether the devices are connected or not. The exact driver version
from the installer package is installed. Updating drivers in this way enables the upgrade
to higher driver versions as well as allowing the installation of older versions. The driver
installation behaves in the same way as first time installation.
вЂў The installer can remove the driver software for a PnP device. This step can be performed by
calling the installation program with a command line option or by using the appropriate option in the Windows control panel, which is created during the driver installation. When the
driver is removed, all device nodes are uninstalled and the pre-installed drivers are removed.
The installer makes sure that all drivers matching the USB VID and PID are removed from
the system. The result is a system that behaves in the same way as if the driver software was
never installed. The device nodes are left uninstalled. When a device is connected to the PC
in this state the Found New Hardware wizard is launched.
USB CDC/EEM Class Driver Reference Manual
35
5 Driver Installation and Uninstallation
The PnP Driver Installer Package supports all current Windows systems including 32 and 64 bit
versions. The Thesycon team provides support and warranty for the product. A comprehensive
documentation is part of the demo package available at http://www.thesycon.de/pnpinstaller.
36
USB CDC/EEM Class Driver Reference Manual
6
Debug Support
6 Debug Support
6.1 Event Log Entries
If the driver detects a major problem during the startup process, it creates an entry in the event log
of the system. The event log can be opened with the context menu on вЂ™My ComputerвЂ™ -> Manage
-> Event Viewer -> System. The entries are created in the category error.
Common problems are:
6.1.1 Clear Feature Endpoint Halt
The device cannot handle this request. Solution: Set the flag SendClearEpHaltOnStart to
0.
6.1.2 Demo is Expired
The demo version has an internal clock. If the demo period has expired, the driver fails all operations. To re-enable the driver, reboot the PC. This does not occur with the licensed version.
6.2 Enable Debug Traces
The licensed version of the driver package contains the debug version of the driver. The debug
version of the driver can generate text messages on a kernel debugger or a similar application.
These messages can help to analyze problems.
To enable the debug traces follow these steps.
вЂў Install the drivers created in the folder driver_package\debug created by
create_drvpackages.cmd.
вЂў Open the registry editor with the path:
\HKEY_LOCAL_MACHINE\System\CurrentControlSet\services\
YOUR_SERVICE_NAME\.
YOUR_SERVICE_NAME is the base name used during customization.
Edit the DWORD value key TraceMask. The messages are grouped in special topics. Each
topic can be enabled with a bit in the debug mask. To enable the messages on bit 8 the
TraceMask must be set to 0x00000100. The TraceMask contains the bitwise combination
of all active message bits.
вЂў On Windows Vista and later an additional registry key must be created:
\HKLM\system\CurrentControlSet\Control\Session Manager\Debug Print Filter In
this
key a DWORD value with name DEFAULT and the value 0xf must be created. This enables
the system debug print filter. The system must be rebooted to activate the new setting.
вЂў Disconnect all devices or reboot the PC to make sure the driver is loaded again. The driver
reads the registry key TraceMask if it is started.
USB CDC/EEM Class Driver Reference Manual
37
6 Debug Support
вЂў Start a kernel debugger like WinDbg or an application like DebugView to receive the kernel
traces. DebugView is a free software that can be downloaded on the Microsoft web page.
Connect your device.
вЂў If your problem ends up in a blue screen of death or you see an unexpected re-boot of the
PC, please change the following settings: System Properties -> Advanced -> Startup and
Recovery -> Settings -> Write Debugging Information to "Kernel Memory Dump". Set the
registry key TraceLogSizeKB in the same location as the TraceMask to 128. This
includes the last 128kb traces to the memory dump. Reproduce the BSOD again. Transfer
the memory dump (typically %SystemRoot%\MEMORY.DMP) to Thesycon for analysis.
The following table summarizes the meaning of the debug bits.
Table 1: Trace Mask Bit Content
Bit
Content
0
Fatal errors
1
Warnings
2
Information
3
Extended information
8
USB RX handling
9
USB TX handling
10
USB data dump beginning of each buffer
12
NDIS OID requests
13
Dump of Ethernet frames
14
NDIS RX handling
15
NDIS TX handling
16
NDIS Statistics requests
If you submit a problem description to Thesycon please include the following:
вЂў operating system and Service Pack
вЂў USB host controller (XHC, EHC, UHC, OHC) and usage of external USB hubs
вЂў Driver version and vendor of the host controller driver
38
USB CDC/EEM Class Driver Reference Manual
6
Debug Support
вЂў Driver version and driver build (release/debug/demo) that has been used
вЂў used TraceMask if kernel Traces have been recorded
вЂў The actions you have performed to cause the problem
Do not send large memory dumps with e-mail. We can provide a FTP account.
USB CDC/EEM Class Driver Reference Manual
39
References
7 Related Documents
References
[1] Universal Serial Bus Specification 1.1,
http://www.usb.org
[2] Universal Serial Bus Specification 2.0,
http://www.usb.org
[3] Universal Serial Bus Specification 3.0,
http://www.usb.org
[4] USB device class specifications (CDC, EEM etc.),
http://www.usb.org
[5] Microsoft Developer Network (MSDN) Library,
http://msdn.microsoft.com/library/
[6] Windows Driver Development Kit,
http://msdn.microsoft.com/library/
[7] Windows Platform SDK,
http://msdn.microsoft.com/library/
USB CDC/EEM Class Driver Reference Manual
41

Download Report