HP 5991-7955 User Manual

HP Integrity Computer Systems HP-UX 11i v2 to 11i v3 Network Driver Migration Guide

HP Part Number: 5991-7955 Published: E0207

Legal Notices

This document contains information which is protected by copyright. All rights are reserved. Reproduction, adaption, or translation without

prior written permission is prohibited, except as allowed under the copyright laws.

Restricted Rights Legend. Use, duplication or disclosure by the U.S. Government Department of Defense is subject to restrictions as set forth in

paragraph (b)(3)(ii) of the Rights in Technical Data and Software clause in FAR 52.227-703.

This software and documentation is based in part on the Fourth Berkeley Software Distribution under license from the Regents of the University

of California.

Warranty. A copy of the specific warranty terms applicable to your Hewlett-Packard product and replacement parts can be obtained from your

local Sales and Service Office.

Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to,

the implied warranties of merchantability and fitness for a particular purpose.

Hewlett-Packard shall not be liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with

the furnishing, performance, or use of this material.

Printing History

New editions of this manual will incorporate all material updated since the previous edition. The manual printing date and part number indicate

its current edition. The printing date changes when a new edition is printed. (Minor corrections that are incorporated at a reprinting do not cause

the date to change.) The manual part number changes when extensive technical changes are incorporated.

Edition Part Number Date

First/5187-4493/September 2003

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:

http://www.hp.com/go/hpux_ddk

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

Publication DateSupported Product VersionsOperating Systems SupportedDocument Manufacturing Part

Number

February 200711.31.0211i v35187-4493

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

KeyCap The name of a keyboard key. Note that Return and Enter both refer to the

same key.

Emphasis Text that is emphasized.

Bold Text that is strongly emphasized. Bold The defined use of an important word or phrase.

ComputerOut

UserInput

Command

Variable

[ ] The contents are optional in formats and command descriptions. If the contents

{ } The contents are required in formats and command descriptions. If the contents

... The preceding element may be repeated an arbitrary number of times. | Separates items in a list of choices.

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.

are a list separated by |, you must choose one of the items.

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 -r option returns the release identifier. This table shows the releases available for HP-UX 11i.

Table 2 HP-UX 11i Releases

Supported Processor ArchitectureRelease NameRelease

Identifier

PA-RISC and Itanium®HP-UX 11i v3B.11.31.02

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

Figure 1-1 HP-DLPI LAN Driver Architecture

PCI Bus

HP-DLPI to Driver Inter face

DLP

I 2.0 API

wit

h HP Extensions vi

a STREAMS

Inter faces

Ethernet

Card

HP-DLPI Infrastructure

Tightly Coupled

WSIO Network Interface

Driver for Ethernet

MAC types

HP-UX Kernel

Services

WSI

O

Services

STREAMS

Services

NetTL

Services

Upper layers of the HP-UX Network Interface Architecture

Data Link Layer

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 ne

twork 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 se

rvices for use by upper layers 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 demultipl

exing, promiscuous/multicast filtering and

handling of IEEE XID/TEST f

rames. Outbound frame processing: building the LLC/MAC headers be

fore handoff to drivers

. .

. . .

. .

.

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

• Inform HP-DLPI each time the MAC address changes. This is required for LAN commands

PCI Bus

HP-DLPI to Driver Inter face

DLPI 2.0 API with HP Extensions via STREAMS Inter faces

Ethernet

Card

Token Ring

Card

Card for my MAC

ATM, X.25, etc.

FDDI Card

HP-DLPI Infrastructure

HP-UX Kernel

Services

WSIO

Services

STREAMS

Services

NetTL

Services

Upper layers of the HP-UX Network Interface Architecture

Data

Link

Layer

Interface repository services for registration and update of network interface information

Other services are available only to tightly coupled drivers

.

WSIO Network

Interface Driver

for any

MAC type

STREAMS driver with native DLPI Implementation

Loosely Coupled

Driver

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

LAN Driver Architecture 15

16

2 Native STREAMS DLPI LAN Driver Migration

The dl_hp_create_info_t data 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_REQ and DL_HP_USAGE_INFO_ACK primitives 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_req routine 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_REQ and DL_HP_USAGE_INFO_ACK primitives 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 nwmgr command is a new LAN command, replacing the lanadmin, lanscan, and linkloop commands, which have been obsoleted.

The nwmgr command 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 nwmgr driver-specific shared library for a Native STREAMS DLPI driver is provided as part of the ENET sample driver under the misc/netmgr directory 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/ncweb directory 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

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

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_t data 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_DOWN is 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 nwmgr command is a new LAN command, replacing the lanadmin, lanscan, and linkloop commands, which have been obsoleted in 11i v3.

The nwmgr command 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 nwmgr driver-specific shared library for a Native STREAMS DLPI driver is provided as part of the ENET sample driver under the misc/netmgr directory 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

sample driver under the misc/ncweb directory 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

HP 5991-7955 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Table of Contents

About This Document

1 Overview

LAN Driver Architecture

HP-DLPI LAN Driver Architecture

Native STREAMS DLPI LAN Driver Architecture

2 Native STREAMS DLPI LAN Driver Migration

New LAN Command

New Graphical User Interface

Options Negotiations

3 Non-Native HP-DLPI LAN Driver Migration

New LAN Command

New Graphical User Interface