HP Integrity Computer Systems
HP-UX 11i v2 to 11i v3 Network Driver
Migration Guide
HP Part Number: 5991-7955
Published: E0207
Download from Www.Somanuals.com. All Manuals Search And Download.
Table of Contents
About This Document ........................................................................................................9
1 Overview.......................................................................................................................13
2 Native STREAMS DLPI LAN Driver Migration...........................................................17
3 Non-Native HP-DLPI LAN Driver Migration...............................................................19
Table of Contents
3
Download from Www.Somanuals.com. All Manuals Search And Download.
4
Download from Www.Somanuals.com. All Manuals Search And Download.
List of Figures
5
Download from Www.Somanuals.com. All Manuals Search And Download.
6
Download from Www.Somanuals.com. All Manuals Search And Download.
List of Tables
7
Download from Www.Somanuals.com. All Manuals Search And Download.
8
Download from Www.Somanuals.com. All Manuals Search And Download.
About This Document
This manual lists and describes the changes between HP-UX 11i v2 and 11i v3 that affect a network
driver migration. It also provides information on how to migrate your network driver from
HP-UX 11i v2 to 11i v3.
The document printing date and part number indicate the document’s current edition. The
printing date will change when a new edition is printed. Minor changes may be made at reprint
without changing the printing date. The document part number will change when extensive
changes are made.
Document updates may be issued between editions to correct errors or document product changes.
To ensure that you receive the updated or new editions, you should subscribe to the appropriate
product support service. See your HP sales representative for details.
The latest version of this document can be found on line at:
NOTE: This book contains many examples of C programs to help design device drivers. Because
of page width restrictions, some long lines of code exceed the space available and break in
unintended places. Treat these broken lines as one line. We recommend that you use the sample
files included with this manual when possible, rather than retyping the examples.
Intended Audience
This document is intended for system administrators or developers responsible for porting or
writing drivers. Developers are expected to:
•
•
•
•
Have experience writing programs in the C language.
Have working knowledge of the basic concepts of writing a driver.
Understand the functionality of the hardware for which the driver is being written.
Understand the HP-UX System Administration Tasks manual and performed system
administration.
•
Have working knowledge of the virtual memory, I/O, and file system areas in the HP-UX
and/or UNIX operating systems.
This document is not a tutorial.
Publishing History
Table 1 Publishing History Details
Document Manufacturing Part
Number
Operating Systems Supported Supported Product Versions Publication Date
5187-4493
11i v3 11.31.02 February 2007
Typographical Conventions
This document uses the following conventions.
audit(5)
An HP-UX manpage. In this example, audit is the name and 5 is the section in
the HP-UX Reference. On the web and on the Instant Information CD, it may
be a hot link to the manpage itself. From the HP-UX command line, you can
enter “man audit” or “man 5 audit” to view the manpage. See man(1).
Book Title
The title of a book. On the web and on the Instant Information CD, it may be
a hot link to the book itself.
9
Download from Www.Somanuals.com. All Manuals Search And Download.
KeyCap
The name of a keyboard key. Note that Return and Enter both refer to the
same key.
Emphasis
Bold
Text that is emphasized.
Text that is strongly emphasized.
Bold
The defined use of an important word or phrase.
Text displayed by the computer.
Commands and other text that you type.
A command name or qualified command phrase.
The name of a variable that you may replace in a command or function or
information in a display that represents several possible values.
ComputerOut
UserInput
Command
Variable
[ ]
{ }
The contents are optional in formats and command descriptions. If the contents
are a list separated by |, you must choose one of the items.
The contents are required in formats and command descriptions. If the contents
are a list separated by |, you must choose one of the items.
...
|
The preceding element may be repeated an arbitrary number of times.
Separates items in a list of choices.
HP-UX Release Name and Release Identifier
Each HP-UX 11i release has an associated release name and release identifier. The uname
command with the -roption returns the release identifier. This table shows the releases available
for HP-UX 11i.
Table 2 HP-UX 11i Releases
Release
Identifier
Release Name
Supported Processor Architecture
B.11.31.02
HP-UX 11i v3
PA-RISC and Itanium®
Related Documents
You can find additional information about migration from HP-UX 11i v2 to HP-UX 11i v3 at:
Other documents in this collection include:
•
•
•
•
DDK FAQ
HP-UX 11i v3 Driver Development Guide
HP-UX 11i v3 Driver Development Reference
HP-UX 11i v3 Driver Development Getting Started Guide
HP Encourages Your Comments
HP encourages your comments concerning this document. We are truly committed to providing
documentation that meets your needs.
Please send comments to:
Please include document title, manufacturing part number, and any comment, error found, or
suggestion for improvement you have concerning this document. Also, please include what we
did right so we can incorporate it into other documents.
10
About This Document
Download from Www.Somanuals.com. All Manuals Search And Download.
Email & Internet Resources
Interface program and developer resource materials are available at the following locations:
•
Interface Program E-mail at:
•
Developer Resource at:
Support and Compatibility Disclaimers
Because drivers function at the level of the kernel, HP reminds you of the following:
•
Adding your own driver to HP-UX requires relinking the driver into HP-UX. With each
new release you should plan on recompiling your driver in order to reinstall it into the new
HP-UX kernel. Many header files do not change. However, drivers typically use some header
files that could change across releases (you might have some system dependencies).
•
•
HP provides support services for HP products, including HP-UX. Products, including drivers,
from non-HP parties receive no support, other than the support of those parts of a driver
that rely on the documented behavior of supported HP products.
If difficulties arise during the development and test phases of writing a driver, HP may
provide assistance in isolating problems to determine if:
—
—
HP hardware is not at fault; and
HP software (firmware) is not at fault by removing user-written kernel drivers.
•
When HP hardware, software, and firmware are not at fault, you should seek help from the
third party from whom you obtained software or hardware.
11
Download from Www.Somanuals.com. All Manuals Search And Download.
12
Download from Www.Somanuals.com. All Manuals Search And Download.
1 Overview
The HP-UX 11i v2 to 11i v3 Network Driver Migration Guide provides 3rd party developers a
resource to understand the HP-UX network stack architecture and network API changes between
HP-UX 11i v2 and 11i v3 and an overview for migrating network drivers from HP-UX 11i v2 to
11i v3.
This document describes how to migrate HP-DLPI based LAN drivers and native STREAMS
DLPI based LAN drivers.
HP strongly encourages developers to write HP-DLPI based LAN drivers instead of native
STREAMS DLPI based LAN drivers because of the many advantages of the HP-DLPI based LAN
drivers model. The developers save time by using the HP-DLPI implemention; they do not have
to write one of their own. This results in a better time-to-market for their product and reduced
maintance costs.
LAN Driver Architecture
HP-UX 11i v3 exports HP-DLPI interfaces for network drivers. A driver written to the HP-DLPI
interface is called a non-native HP-DLPI driver (also referred to as a tightly coupled driver). A
driver that includes its own implementation of the data link layer written to DLPI standards is
called a native STREAMS DLPI driver (also referred to as a loosely coupled driver).
HP-DLPI LAN Driver Architecture
HP-DLPI LAN drivers utilize HP-DLPI for the following operations and features:
•
HP-DLPI is the interface between the transport and driver layer. An advantage of writing
a non-native driver is that HP-DLPI assumes the responsibility of interacting with the
transport layer.
•
•
Support for SMH and LAN commands is provided in the non-native driver architecture.
HP-DLPI provides support for Out-of-Packet (OOP) and Checksum-offload (CKO).
Figure 1-1 shows the HP-UX 11i v3 HP-DLPI LAN driver architecture.
LAN Driver Architecture
13
Download from Www.Somanuals.com. All Manuals Search And Download.
Figure 1-1 HP-DLPI LAN Driver Architecture
Upper layers of the HP-UX Network Interface Architecture
DLPI 2.0 API
with
HP Extensions
via STREAMS
Interfaces
HP-DLPI Infrastructure
Implementation of DLPI 2.0 API and HP extensions to the
API for use by upper layers
.
.
.
Defines the HP-DLPI to driver interface
Interface repository services for registration and update
of network interface information
Facilitates option negotiation by the network protocol
layer based on the driver features or options.
Fast path support
Provides connection oriented, connection less and raw
mode services for use by upper layers
.
Data
Link
Layer
.
.
STREAMS
Services
.
.
Event notification between upper layers and drivers
Processing of protocol, mulitcast and promiscuous
requests and a repostitory for such control information
Inbound frame processing, including protocol
demultiplexing, promiscuous/multicast filtering and
handling of IEEE XID/TEST frames.
.
.
Outbound frame processing: building the LLC/MAC
headers before handoff to drivers
HP-DLPI to
Driver Interface
HP-UX
Kernel
Services
Tightly Coupled
WSIO Network Interface
Driver for Ethernet
MAC types
NetTL
Services
WSIO
Services
PCI Bus
Ethernet
Card
For information on writing an HP-DLPI LAN driver, see the HP-UX 11i v3 Driver Development
Guide.
Native STREAMS DLPI LAN Driver Architecture
Native STREAMS DLPI LAN drivers are also known as loosely-coupled drivers. Developers can
continue to have the option of providing a native DLPI implementation for HP-UX 11i v3. This
requires the developer to provide a full DLPI 2.0+HP extensions (for example, DL_HP_PPA_REQ)
support module.
A native LAN driver must do the following:
•
Register with HP-DLPI during initialization. This is required because on HP-UX the HP-DLPI
module also acts as the central repository of all networking interfaces installed on the system.
The native STREAMS DLPI driver has its own DLPI implements.
•
Inform HP-DLPI every time its hardware state changes.
14
Overview
Download from Www.Somanuals.com. All Manuals Search And Download.
•
•
Inform HP-DLPI each time the MAC address changes. This is required for LAN commands
to display the current MAC address.
Support specific ioctls, standard DLPI primitives, and specific HP extensions of DLPI
primitives. This ensures the driver will work with standard HP-UX LAN commands and
SMH.
For information on writing a Native driver, see the HP-UX 11i v3 Driver Development Guide. Key
native-to-native driver migration issues are noted in the next section of this document.
Figure 1-2 shows the native driver architecture.
Figure 1-2 Native LAN Driver Architecture
Upper layers of the HP-UX Network Interface Architecture
DLPI 2.0 API
with
HP Extensions
via STREAMS
Interfaces
HP-DLPI Infrastructure
Loosely Coupled
Driver
.
.
Interface repository
STREAMS
Services
services for registration
and update of network
interface information
STREAMS driver
with native DLPI
Implementation
HP-UX
Kernel
Services
HP-DLPI
to
Driver
Interface
Other services are
available only to
tightly coupled
drivers
Data
Link
Layer
WSIO Network
Interface Driver
for any
NetTL
Services
MAC type
WSIO
Services
PCI Bus
FDDI
Card
Card for my MAC
ATM, X.25, etc.
Ethernet
Card
Token Ring
Card
LAN Driver Architecture
15
Download from Www.Somanuals.com. All Manuals Search And Download.
16
Download from Www.Somanuals.com. All Manuals Search And Download.
2 Native STREAMS DLPI LAN Driver Migration
The dl_hp_create_info_tdata structure that is used during registration of the driver with
HP-DLPI has been extended with the following new fields. These new fields must be set
appropriately before registering with HP-DLPI:
•
•
•
dhc_features_one_cap
dhc_features_two_cap
dhc_features_three_cap
To accommodate the new fields in the dl_hp_create_info_t structure in HP-UX 11i v3, the
dhc_version data field must be set to 3; registration of version 2 drivers will fail.
The DL_HP_USAGE_INFO_REQand DL_HP_USAGE_INFO_ACKprimitives and data structures
associated with them have been modified in 11i v3. The 11i v3 method of implementing this
primitive is provided in the ENET sample driver. See the enet_dlpi_usage_info_reqroutine
in the ENET sample driver for detailed information on how to modify your driver for 11i v3 to
support this primitive.
NOTE: The DL_HP_USAGE_INFO_REQand DL_HP_USAGE_INFO_ACKprimitives are HP
extension to the DLPI standard. The definitions and structures associated with these primitives
are likely to undergo modifications in immediate future releases to HP-UX 11i v3. Use this
information in your network interface driver for HP-UX 11i v3.
New LAN Command
Starting with HP-UX 11i v3, the nwmgrcommand is a new LAN command, replacing the
lanadmin, lanscan, and linkloopcommands, which have been obsoleted.
The nwmgrcommand supports driver-specific shared libraries. In addition, it comes with a
common services shared library that provides most of the services required by a driver specific
shared library. For information on how to develop a driver-specific shared library for your
networking driver, see the “LAN Commands” chapter in the HP-UX 11i v3 Driver Development
Guide.
A fully functional nwmgrdriver-specific shared library for a Native STREAMS DLPI driver is
provided as part of the ENET sample driver under the misc/netmgrdirectory in the ENET
driver sources. HP recommends that you use this shared library as a starting point instead of
writing one from scratch.
New Graphical User Interface
Starting with HP-UX 11i v3, a new Graphical User Interface (GUI) has been introduced to discover
and configure network interface cards. It is part of the new HP System Management Homepage
(SMH) web-based GUI and replaces the legacy SAM GUI, which have been obsoleted in 11i v3.
The SMH NIC Tool supports driver-specific shared libraries to enable IHVs to provide
driver-specific extensions. For information on how to develop a driver-specific shared library
for your networking driver, see the “Supporting the HP SMH NIC Tool in LAN Drivers” chapter
in the HP-UX 11i v3 Driver Development Guide. In addition, a fully functional SMH NIC Tool
driver specific shared library for a Native STREAMS DLPI driver is provided as part of the ENET
sample driver under the misc/ncwebdirectory in the ENET driver sources. HP recommends
that you use this shared library as a starting point instead of writing one from scratch.
Options Negotiations
HP -DLPI provides a set of ioctls for the in-kernel STREAMS DLS user (for example, IP) to
negotiate with the driver and setup a fastpath. These ioctls are specific to HP-UX. Since they
New LAN Command
17
Download from Www.Somanuals.com. All Manuals Search And Download.
were introduced in HP-UX 11.00, the semantics of the ioctls has not changed. However, the
information provided to the DLS user has changed. The interface was originally intended for IP
only, but it is DLS-user independent in HP-UX 11i v3.
NOTE: Information on how options negotiations are done between a transport layer entity and
HP-DLPI is described in the “Understanding OOP and Transport IOCTLs” chapter in the HP-UX
11i v3 Driver Development Guide. A native driver will act like HP-DLPI when it conducts option
negotiation with a transport layer entity.
18
Native STREAMS DLPI LAN Driver Migration
Download from Www.Somanuals.com. All Manuals Search And Download.
3 Non-Native HP-DLPI LAN Driver Migration
A non-native Networking driver relies on the HP-DLPI layer to interface with the transport layer.
A driver has to conform to the DLPI/driver interface specifications. Descriptions of how to write
a non-native driver are provided in the “Writing a LAN Driver Under HP-DLPI” chapter in the
HP-UX 11i v3 Driver Development Guide . For information on the HP-DLPI interfaces, see the
HP-DLPI manpages in the HP-UX 11i v3 Driver Development Reference.
The dl_hp_create_info_tdata structure that is used during registration of the driver with
HP-DLPI has been extended with the following new fields. These new fields must be set
appropriately before registering with HP-DLPI:
•
•
•
dhc_features_one_cap
dhc_features_two_cap
dhc_features_three_cap
The dhc_version data field must be set to 3 in 11i v3. Starting with 11i v3, registration of version
2 drivers will fail.
Starting with HP-UX 11i v3, non-native DLPI LAN drivers can set the following new features
bits in the dhc_features_one field if the relevant functionality is supported in the driver:
• DL_HP_DRV_USAGE_INFO
• DL_HP_DRV_SUPP_CRA
The HP-DLPI event entry point now supports a new event, DL_HP_EVENT_OLD. Drivers that
support online deletion can now use this event to ensure that all outbound data path and control
requests from DLPI to the driver are quiesced prior to the deletion of a driver instance. Non-native
HP-DLPI based drivers must ensure that the cause information that is passed on
DL_HP_EVENT_LINK_DOWNis correct as this information could be retrieved and used by nwmgr,
the SMH NIC Tool GUI, and Critical Resource Analysis (CRA) tools.
New LAN Command
Starting with HP-UX 11i v3, the nwmgrcommand is a new LAN command, replacing the
lanadmin, lanscan, and linkloopcommands, which have been obsoleted in 11i v3.
The nwmgrcommand supports driver-specific shared libraries. In addition, it comes with a
common services shared library that provides most of the services required by a driver specific
shared library. For information on how to develop a driver-specific shared library for your
networking driver, see the “LAN Commands” chapter in the HP-UX 11i v3 Driver Development
Guide.
A fully functional nwmgrdriver-specific shared library for a Native STREAMS DLPI driver is
provided as part of the ENET sample driver under the misc/netmgrdirectory in the ENET
driver sources. HP recommends that you use this shared library as a starting point instead of
writing one from scratch.
New Graphical User Interface
Starting with HP-UX 11i v3, a new Graphical User Interface (GUI) has been introduced to discover
and configure network interface cards. It is part of the new HP System Management Homepage
(SMH) web-based GUI and replaces the legacy SAM GUI, which have been obsoleted in 11i v3.
The SMH NIC Tool supports driver-specific shared libraries to enable IHVs to provide
driver-specific extensions. For information on how to develop a driver-specific shared library
for your networking driver, see the “Supporting the HP SMH NIC Tool in LAN Drivers” chapter
in the HP-UX 11i v3 Driver Development Guide. In addition, a fully functional SMH NIC Tool
driver specific shared library for a Native STREAMS DLPI driver is provided as part of the ENET
New LAN Command
19
Download from Www.Somanuals.com. All Manuals Search And Download.
sample driver under the misc/ncwebdirectory in the ENET driver sources. HP recommends
that you use this shared library as a starting point instead of writing one from scratch.
20
Non-Native HP-DLPI LAN Driver Migration
Download from Www.Somanuals.com. All Manuals Search And Download.
|