OpenSS7

OpenSS7 DLPI Porting Guide

About This Manual

This is Edition 7.20141001, last updated 2014-10-25, of The OpenSS7 DLPI Porting Guide, for Version 1.1 release 7.20141001 of the OpenSS7 package.


Preface


Notice

This package is released and distributed under the AGPL (see GNU Affero General Public License). Please note, however, that there are different licensing terms for the manual pages and some of the documentation (derived from OpenGroup1 publications and other sources). Consult the permission notices contained in the documentation for more information.

This manual is released under the FDL (see GNU Free Documentation License) with no invariant sections.


Abstract

This manual provides a DLPI Porting Guide for OpenSS7.

Objective

The objective of this manual is to provide a porting guide for the STREAMS and DLPI programmer when porting STREAMS drivers, modules and applications to OpenSS7 from other major implementations of DLPI, such as AIX, AIXlink/X.25, Digital UNIX, HP-UX, IRIX, OSF, PowerMAX, Solaris, Solstice X.25, SVR4.2, Tru64 UNIX, UnixWare, and others.

This guide provides information to developers on the use of the DLPI interfaces and drivers at the user and kernel levels as well as the difference between the OpenSS7 implementation of DLPI drivers and those of these other systems.

Intent

The intent of this manual is to act as a guide to porting DLPI STREAMS modules, drivers and applications programs from other UNIX implementations of DLPI to Linux Fast-STREAMS2. It is intended to be read alone and is not intended to replace or supplement the OpenSS7 manual pages. For a reference for writing code, the manual pages (see dlpi(7)) provide a btter reference to the programmer. Although this describes the features of the OpenSS7 package, OpenSS7 Corporation is under no obligation to provide any software, system or features listed herein.

Audience

This manual is intended for a highly technical audience. The reader should already be familiar with Linux kernel and user application programming, the Linux file system, character devices, driver input and output, interrupts, software interrupt handling, scheduling, process contexts, multiprocessor locks, thread programming, POSIX porgramming, etc.

This guide is intended for network and systems programmers, who use the STREAMS and DLPI mechanism at user and kernel levels for Linux and UNIX system communications services. Readers of the guide are expected to possess prior knowledge of the Linux and UNIX system, programming, networking, and data communication.

To derive maximum use from this porting guide, it is intended that the reader also be familiar with the user of STREAMS and DLPI under UNIX and POSIX systems implementing DLPI drivers and applications libraries. The reader should certainly be familiar with the DLPI implementations on the UNIX or POSIX system from which STREAMS drivers, modules or applications are being ported.


Revisions

Take care that you are working with a current version of this manual: you will not be notified of updates. To ensure that you are working with a current version, contact the Author, or check The OpenSS7 Project website for a current version.

A current version of this manual is normally distributed with the OpenSS7 package, openss7-1.1.7.20141001.3

Version Control

$Log: dlpi_porting.texi,v $
Revision 1.1.2.2  2011-02-07 02:21:33  brian
- updated manuals

Revision 1.1.2.1  2009-06-21 10:40:08  brian
- added files to new distro

ISO 9000 Compliance

Only the TeX, texinfo, or roff source for this manual is controlled. An opaque (printed, postscript or portable document format) version of this manual is an UNCONTROLLED VERSION.


Disclaimer

OpenSS7 Corporation disclaims all warranties with regard to this documentation including all implied warranties of merchantability, fitness for a particular purpose, non-infringement, or title; that the contents of the manual are suitable for any purpose, or that the implementation of such contents will not infringe on any third party patents, copyrights, trademarks or other rights. In no event shall OpenSS7 Corporation be liable for any direct, indirect, special or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with any use of this manual or the performance or implementation of the contents thereof.

OpenSS7 Corporation reserves the right to revise this software and documentation for any reason, including but not limited to, conformity with standards promulgated by various agencies, utilization of advances in the state of the technical arts, or the reflection of changes in the design of any techniques, or procedures embodied, described, or referred to herein. OpenSS7 Corporation is under no obligation to provide any feature listed herein.

U.S. Government Restricted Rights

If you are licensing this Software on behalf of the U.S. Government ("Government"), the following provisions apply to you. If the Software is supplied by the Department of Defense ("DoD"), it is classified as "Commercial Computer Software" under paragraph 252.227-7014 of the DoD Supplement to the Federal Acquisition Regulations ("DFARS") (or any successor regulations) and the Government is acquiring only the license rights granted herein (the license rights customarily provided to non-Government users). If the Software is supplied to any unit or agency of the Government other than DoD, it is classified as "Restricted Computer Software" and the Government’s rights in the Software are defined in paragraph 52.227-19 of the Federal Acquisition Regulations ("FAR") (or any successor regulations) or, in the cases of NASA, in paragraph 18.52.227-86 of the NASA Supplement to the FAR (or any successor regulations).


Acknowledgements

As with most open source projects, this project would not have been possible without the valiant efforts and productive software of the Free Software Foundation, the Linux Kernel Community, and the open source software movement at large.


Sponsors

Funding for completion of the OpenSS7 OpenSS7 package was provided in part by:

Monavacon Limited
OpenSS7 Corporation

Additional funding for The OpenSS7 Project was provided by:

Monavacon LimitedOpenSS7 Corporation
AirNet CommunicationsComverse Ltd.
eServGlobal (NZ) Pty Ltd.Excel Telecommunications
France TelecomGeoLink SA
HOB InternationalLockheed Martin Co.
MotorolaNetCentrex S. A.
Newnet Communications, Inc.Nortel Networks
Peformance Technologies, Inc.Sonus Networks Inc.
SS8 Networks Inc.SysMaster Corporation
TECORETumsan Oy
VerisignVodare Ltd.

Contributors

The primary contributor to the OpenSS7 OpenSS7 package is Brian F. G. Bidulock. The following is a list of notable contributors to The OpenSS7 Project:

- Per Berquist- Kutluk Testicioglu
- John Boyd- John Wenker
- Chuck Winters- Angel Diaz
- Peter Courtney- Jérémy Compostella
- Tom Chandler- Sylvain Chouleur
- Gurol Ackman- Christophe Nolibos
- Pierre Crepieux- Bryan Shupe
- Christopher Lydick- D. Milanovic
- Omer Tunali- Tony Abo
- John Hodgkinson- Others

Supporters

Over the years a number of organizations have provided continued support in the form of assessment, inspection, testing, validation and certification.


Telecommunications

Integrated Telecom SolutionsAASTRA
Accuris NetworksAculab
AdaxAEPONA
AirNet CommunicationsAirwide Solutions
AlacreAlcatel
Alcatel-LucentAltobridge
AnamApertio (now Nokia)
Alaska Power & TelephoneAricent
Artesyn (now Emerson)Arthus Technologies
Bharti TelesoftBubbleMotion
Continuous Computing (Trillium)Cellnext Solutions Limited
CiscoCodent Networks
Cogeco Cable Inc.Comverse Ltd.
Condor NetworksCoral Telecom
CorecessCorelatus
CosiniData Connection
DatacraftDatatek Applications Inc.
DatatronicsDialogic
DigiumDruid Software
DTAG (Deutsche Telecom AG)Empirix
Engage Communication Inc.Ericsson
eServGlobal (NZ) Pty Ltd.ETSI
Excel TelecommunicationsFlextronics (now Aricent)
France TelecomGemini Mobile Technologies
Geolink (now SeaMobile)Global Edge
HuaweiIBSYS Canada
Integral Access (now Telco Systems)Integrat Mobile Aggregation Services
Kineto WirelessLucent
Maestro CommunicationsMCI
MindspeedMobis
MobixellMotivity Telecom, Inc.
MotorolaMpathix Inc.
m-Wise Inc.Myriad Group
Net2PhoneNetCentrex S. A.
NetTest A/S (now Anritsu)NeuvaTel PCS
Newnet Communications, Inc.NMS (now Dialogic)
Noble Systems CorporationNokia
Nortel Networksj2 Global Communications, Inc.
OnMobileOrange
OuroborosP3 Solutions GmbH
Primal Technologies Inc.Propolys Pte Ltd.
Peformance Technologies, Inc.Pulse Voice Inc.
Reliance CommunicationsRoamware Inc.
SONORYS Technology GmbHSonus Networks Inc.
Spider Ltd. (now Emerson)SS8 Networks Inc.
Oasis SystemsStratus
Stratus Technologies Bermuda Ltd.Sicap AG
Switchlab Ltd.Synapse Mobile Networks SA
SysMaster CorporationTata Communications
TecoreTekno Telecom LLC
TelcordiaTelecom Italia
TeledesignTelemetrics Inc.
TelnorTE-Systems
Texas Instruments Inc.Tumsan Oy
UlticomVanu Inc.
Vecto Communications SRLVeraz Networks
VeriSignVodare Ltd.
VSE NET GmbHThe Software Group Limited
WINGcon GmbHWipro Technologies
Xentel Inc.YCOM SA
ZTE Corporation

Aerospace and Military

Advanced TechnologiesAltobridge
AltobridgeBBN (Bolt, Beranek, and Neuman)
ARINCBoldon James
ATOS OriginLockheed Martin Co.
BoeingNorthrop Grumman Corporation
Boldon JamesQinetiQ
CRNASAAB
DSNA-DGAC 4Sandia National Laboratories
DLR 5Thales
DSNA-DTIWright-Patterson Air Force Base
Egis-Avia (Sofreavia)
MetaSlash, Inc.
Sofreavia
FAA WJHTC6
Thales ATM/Air Systems

Financial, Business and Security

AlebraAlebra
Automated Trading Desk (now Citi)Boldon James
Banco CredicoopFujitsu-Seimens
BeMacFutureSoft
Boldon JamesGSX
CyberSource CorporationHOB International
Fujitsu-SeimensHP (Hewlett-Packard)
FutureSoftIBM
Gcom, Inc.
GSX
HOB International
HP (Hewlett-Packard)
IBM
Lightbride (now CyberSource)
MasterCardAlert Logic
Network Executive Software Inc.Apani
Packetware Inc.BeMac
Packetware Inc.ERCOM
Prism Holdings Ltd.Hitech Systems
S2 Systems (now ACI)iMETRIK
Symicron Computer Communications LimitedIntrado Inc.

Education, Health Care and Nuclear Power

IEEE Computer SocietyAteb
ENST 7Mandexin Systems Corporation
HTW-Saarland 8
Kansas State UniversityAreva NP
University of North Carolina CharlotteEuropean Organization for Nuclear Research

Agencies

It would be difficult for the OpenSS7 Project to attain the conformance and certifications that it has without the free availability of specifications documents and standards from standards bodies and industry associations. In particular, the following:

3GPP (Third Generation Partnership Project)
ATM Forum
EIA/TIA (Electronic Industries Alliance)
ETSI (European Telecommunications Standards Institute)
ICAO (International Civil Aviation Organization)
IEEE (Institute of Electrical and Electronic Engineers)
IETF (The Internet Engineering Task Force)
ISO (International Organization for Standardization)
ITU (International Telecommunications Union)
Mulutiservices Forum
The Open Group

Of these, ICAO, ISO, IEEE and EIA have made at least some documents publicly available. ANSI is notably missing from the list: at one time draft documents were available from ANSI (ATIS), but that was curtailed some years ago. Telecordia does not release any standards publicly. Hopefully these organizations will see the light and realize, as the others have, that to remain current as a standards organization in today’s digital economy requires providing individuals with free access to documents.


1 Introduction

This guide documents the porting of DLPI STREAMS modules, drivers and applications programs from various UNIX implementations to Linux Fast-STREAMS9.


1.1 Overview

This guide documents the porting of DLPI drivers, modules and applications programs from various UNIX implementations of DLPI to Linux Fast-STREAMS10. It details some of the differences between other implementations of DLPI and that of Linux Fast-STREAMS11.

In addition, it provides documentation on STREAMS drivers and modules for DLPI including:


1.2 Organization

This manual is organized (loosely) into several sections as follows:


1.3 Conventions

This manual uses texinfo typographic conventions.


1.4 Concepts


2 Porting

This guide is largely focused on porting STREAMS drivers, modules and applications programs that act in the capacity of a DLS User. Whereas other documents tend to focus on simply porting drivers for specific interface cards, that topic is adequately addressed elsewhere for the Linux kernel.12 Whenever a network device driver has been written for a device under Linux, using Linux paradigms and procedures, it can automatically work with DLPI. Therefore, this guide focusses on the differences between the DLPI interfaces that would be experienced by the DLS User: STREAMS modules that push over DLPI Streams; STREAMS drivers under which DLPI Streams are linked; and applications programs that access the DLPI interface directly as a user-space program.

Linux Fast-STREAMS and each of its add-on packages, including OpenSS7, ship with a wide assortment of manual pages. Most manual pages contain a section entitled “COMPATIBILITY” that provides compatibility and porting information for various mainstream UNIX implementations. For information on the minor differences in the STREAMS environment, see the Linux Fast-STREAMS package, streams-0.9.2.4.

There are hundreds of manual pages in the OpenSS7 package for DLPI. These manual pages can be explored best by starting with the dlpi(7) manual page. The manual pages document both DLPI Revision 2.0.0 standard behaviour, as well as the OpenSS7 implementations of extension primitives, input-output controls, and features documented for other operating systems including AIX, AIXlink/X.25, HP-UX, IRIX, OSF, PowerMAX, Solaris, Solstice X.25, SVR 4, SVR 4.2MP, UnixWare 7. Although each of the DLPI related manual pages of supported functions, primitives and structures provide compatibilty and porting information, this document attempts to gather together pertinent information concerning porting DLPI modules, drivers and applications programs from various UNIX operating systems supporting STREAMS and DLPI to OpenSS7.


2.1 Porting Organization

The porting information in this guide is organized by the flavor of operating system from which porting is being attempted. Note that, aside from configuration details, any system not listed here that is based on SVR 4, SVR 4.2MP, or on another of the implementations, should start with that implementation’s portability information. Porting information is included for porting from implementations based on a strict interpretation of the DLPI standards, the AIX operating system and the AIXlink/X.25 package, the HP-UX operating system, the IRIX operating system, the the OSF, Digital UNIX, or Tru64 UNIX operating system, the PowerMAX operating system, the Solaris operating system and the Solstice X.25 or SunLink X.25 packages, the SVR 4 and SVR 4.2MP operating system, and the UnixWare 7 operating system.

Note that additional porting information with regard to porting X.25 applications from various implementations to Linux Fast-STREAMS is detailed in the X.25 Porting Guide which is part of the OpenSS7 X.25 package (strx25).

Porting information is organized into sections as follows:

Porting from DLPIPorting general DLPI applications.
Porting from AIXPorting AIX DLPI applications.
Porting from AIXlink/X.25Porting AIXlink/X.25 DLPI applications.
Porting from HP-UXPorting HP-UX DLPI applications.
Porting from IRIXPorting IRIX DLPI applications.
Porting from OSFPorting OSF DLPI applications.
Porting from PowerMAXPorting PowerMAX DLPI applications.
Porting from SolarisPorting Solaris DLPI applications.
Porting from Solstice X.25Porting Solstice X.25 DLPI applications.
Porting from SVR4.2Porting SVR4.2 DLPI applications.
Porting from UnixWarePorting UnixWare DLPI applications.
Developing on OpenSS7Developing DLPI applications on OpenSS7.
Porting from DLPIPorting general DLPI applications.
Porting from AIXPorting AIX DLPI applications.
Porting from AIXlink/X.25Porting AIXlink/X.25 DLPI applications.
Porting from HP-UXPorting HP-UX DLPI applications.
Porting from IRIXPorting IRIX DLPI applications.
Porting from OSFPorting OSF DLPI applications.
Porting from PowerMAXPorting PowerMAX DLPI applications.
Porting from SolarisPorting Solaris DLPI applications.
Porting from Solstice X.25Porting Solstice X.25 DLPI applications.
Porting from SVR4.2Porting SVR4.2 DLPI applications.
Porting from UnixWarePorting UnixWare DLPI applications.
Developing on OpenSS7Developing DLPI applications on OpenSS7.

3 General Porting Considerations

There are several aspects of porting from the various environments to Linux Fast-STREAMS that can be categorized roughly by the functional interface to which the aspect corresponds. These apects are:

DLPI Driver Features

This aspect includes support for features that are pervasive over the other aspects, but entail some service or feature that is not provided directly by the DLPI standard specification. Some examples are Raw Mode, LLC2 Mode, Fast Path, and combined Connectionless and Connection-Oriented mode drivers.

DLPI and Extension Primitives

This aspect include support for standard DLPI primitive subsets as well as additional implementation-specific extension primitives not found in the DLPI standard.

DLPI Driver Input-Output Controls

This apsect includes the implementation-specific, or somethimes protocol-specific, input-output controls provided in support of DLPI drivers, modules and add-on libraries.

DLPI Device Drivers and Modules.

This aspect includes the STREAMS device drivers and pushable modules that are provided by an implementation. It also includes the device driver organization (whether split into a generic interface component and a device specific component, or not).

DLPI Support and Add-On Libraries

This aspect includes the shared-object support or add-on libraries that are used to manage or provide application programming interfaces to the DLPI device drivers.

DLPI Support and Management Utilities

This apsect includes utilities provided with the system that support the configuraiton, management or trouble-shooting of DLPI drivers and modules, whether DLPI generic, or protocol-specific.

DLPI Device and Driver Management

This aspect includes SNMP and CMIP agents and the associated MIBs that provide for remote management of the DLPI device drivers and applications.

The sections that follow provide an overview of each of these aspects. Also, each specific porting section has sub-sections that detail each of these aspects for a specific porting scenario.


3.1 Driver Addressing


3.1.1 Driver Naming


3.1.2 PPA Selection

Some DLPI implementations provide only Style 1 drivers (that do not require PPA selection); some provide only Style2 drivers (that require PPA selection); and, some support both Style 1 and Style 2. Others, like AIXlink/X.25 provide a Style 1 driver that acts like a Style 2 driver in that the PPA is encoded in the SAP during bind.

Some Style 2 drivers are multiplexing STREAMS drivers that need PPA-specific Streams linked beneath the multiplexing driver. Other Style 2 drivers have access to all installed PPAs internal to the DLPI driver implementation.

OpenSS7 provides fundamentally Style 2 drivers that have access to all Linux native devices in the system but which can also be individually accessed suing a Style 1 access to the same driver. OpenSS7 has Style 2 PPAs and Style 1 minor device numbers that are based on the ifIndex of the network device.

Style 2 drivers that use a multiplexing STREAMS driver normally have some configuration program that assigns the PPA for each linked Stream. Some implementations provide a mechanism whereby the DLS User can determine which PPAs are available in the system and the characteristics of each PPA. HP-UX provides such a facility.


3.1.3 SAP Addressing

SAP addressing varies somewhat from implementation to implementation for LAPB, HDLC and SDLC; however, most implementations are the same for Ethernet and LLC SAP addressing. For DL_CSMACD, normally if the dl_sap field in the DL_BIND_REQ contains a one-byte value, it is considered to be an LLC SAP. This SAP must be an even number between 0x02 and 0xFE inclusive. For Ethernet media, this results in an 802.2 LLC frame in an 802.3 length indicated frame (length less than or equal to 1536). When the dl_sap field in the DL_BIND_REQ contains a two-byte value, it is considered to be an Ethernet II EtherType. For Ethernet media, the EtherType is carried in the length indicator of the 802.3 frame. For non-Ethernet media supporting LLC, such as FDDI, Token-Ring or ATM, the framing is assumed to be SNAP with the DSAP/SSAP of 0xAAAA, unnumbered information control field (0x03), OUI of 0x000000, and then then two-byte Ethertype, unless the Ethertype SAP bound is itself 0xAAAA or 0xAA. When the SAP bound is 0xAAAA or 0xAA, a subsequent bind operation containing the control field, OUI and protocol identifier is necessary, providing these fields in the dl_sap_length and dl_sap_offset fields of the DL_SUBS_BIND_REQ. Some implementations do no permit two-byte binds on SNAP and require a subsequent bind, where as some will perform Ethernet SNAP automatically on a two-byte bind.

For LAPB, LAPF, LAPD, HDLC and SDLC, some implementations code the logical line number (or TEI or DLCI) in the SAP, as well as whether the station is a primary or secondary station. Some require PPA configuration to determine whether address fields are extended or normal. OpenSS7 automatically determines whether station addresses are extended or normal from the significant bits in the bound SAP, and uses a high byte to determine the role of the station. This is inconsistent accross implementations and compatibility requires porting the DLS user to use the SAP addressing scheme provided by OpenSS7.


3.1.4 Primitive Addresses

For most implemetnations and in normal modes, the address used in the DL_UNITDATA_REQ or DL_CONNECT_REQ or DL_CONNECT_RES primitives require the entire DLSAP of the destination to be specified. For Ethernet operation, this is the 6-byte MAC address (DA) of the destination (for Token Ring the 8-byte full MAC is derived from the 6-byte MAC). For LLC operation, this is the 6-byte MAC address (DA) followed by the one-octet DSAP.

For LLC or SNAP operation, in normal modes the Unnumbered Information control field (0x03) is automatically included by the driver. In LLC2 Mode, on some implemetnations, the DLS User must provide the control field.

Link layer headers are produced automatically in normal modes. The SA and SSAP are determined using the bound SAP and attached PPA, and are typically an individual address. When in the raw mode, addresses are not provided in the DL_UNITDATA_REQ, DL_DATA_REQ or DL_HP_RAWDATA_REQ, and the link layer headers must be completed by the DLS User and included in the data payload of these primitives.


3.1.5 Quality of Service Parameters

Most implementations do not support quality of service parameters.

OpenSS7 supports quality of service parameters using the DL_QOS_CL_RANGE1, DL_QOS_CL_SEL1 DL_QOS_CO_RANGE1, and DL_QOS_CO_SEL1 structure types.


3.2 Driver Features

Driver features that distinguish DLPI implementations tend to be which LAN and WAN protocols are supported directly, and which major modes in which the driver can operate. Most implementations provide direct support for LAN operation, Ethernet, SNAP and LLC Type 1, and support a Raw, LLC2, and Promiscuous Modes. Some implementations go on to support LLC Type 2, WAN operation under LAPB, LAPD and LAPF, and support Fast Path and combined connectionless and connect-oriented modes.

In support of porting from as wide an array of implementations as possible, OpenSS7 provides support for both LAN and WAN operation, all types, except LLC Type 3, and all driver modes.


3.2.1 LAN Operation

Lan operation breaks down into Ethernet, LLC SNAP, LLC Type 1, LLC Type 2, and LLC Type 3 operation. No DLPI implementations support LLC Type 3 directly. Some implementations do not support LLC Type 2 directly, but some provide an LLC2 mode instead. All support Ethernet, SNAP and LLC Type 1.

For as wide a range of portability as possible, OpenSS7 supports EthernetII, SNAP, LLC Types 1 and 2, as well as LLC2 mode. LLC Type 3 is not supported initially.

3.2.1.1 Ethernet and SNAP Operation

All DLPI implementations detailed in this document support EthernetII and ISO/IEC 8802-2 (IEEE 802.2) SNAP operation for providing EthernetII over LLC. Some implementations also support non-Ethernet SNAP for private or experimental protocols.

OpenSS7 also supports EthernetII and SNAP operation and also provides support for non-Ethernet SNAP for private or experimental protocols using the DL_SUBS_BIND_REQ primitive with the DL_HIERARCHICAL_BIND selection.

3.2.1.2 LLC Type 1 Operation

All DLPI implementations detailed in this document support ISO/IEC 8802-2 (IEEE 802.2) LLC Type 1 operation as is required by ISO/IEC 8802-2 (IEEE 802.2) Class I operation.

OpenSS7 supports LLC TYpe 1 in a fashion similar to most implementations through a super-set of standard DLPI primitives, extension primitives, and implementation-specific input-output controls.

3.2.1.3 LLC Type 2 Operation

A number of DLPI implementations detailed in this document support ISO/IEC 8802-2 (IEEE 802.2) LLC Type 2 operation as required for ISO/IEC 8802-2 (IEEE 802.2) Class II or IV operation. Implementations support LLC Type 2 directly are AIX and HP-UX. An add-on package to Solaris also supports LLC Type 2 directly.

Some DLPI implementations support LLC Type 2 indirectly by providing an LLC2 Mode of operation; however, this approach does not include LLC Type 2 state machines and also does not directly support connection-oriented mode data link service. See LLC2 Mode.

OpenSS7 supports both approaches to LLC Type 2. The DLPI driver provides a direct LLC Type 2 approach for STREAMS drivers, modules and applications needing full DLPI DL_CODLS support, as well as a DL_CLDLS LLC2 Mode that supports implementing LLC Type 2 in the DLS user and upper layer protocol modules such as X.25.

3.2.1.4 LLC Type 3 Operation

No DLPI impleentations detailed in this document support ISO/IEC 8802-2 (IEEE 802.2) LLC Type 3 operation directly as would be required for ISO/IEC 8802-2 (IEEE 802.2) Class III or IV operation. There may be some add-on software, but documentation for such software is not readily available.


3.2.2 WAN Operation

Few UNIX implementations support WAN operation (LAPB, LAPF, LAPD) directly. A possible exception is AIX, which appears to integrate a wide range of data links, and UnixWare, which appears to integrate LAPD. Other implementations require add-on or value-add software packages to support WAN links.

The OpenSS7 DLPI driver supports WAN links directly, accessing Linux native raw HDLC network devices supported by the Linux kernel. Additional packages for X.25 and ISDN support STREAMS based raw HDLC network devices in support of LAPB, LAPD and LAPF in a similar fashion. The full range of standard DLPI primitives, implementation specific extension primitives, and implementation specific input-output controls are supported across the WAN link implementations as well.


3.2.3 Driver Modes

Most DLPI implementations support a Promiscuous Mode, and this mode is the only major driver mode for which service primitive support is provided in the DLPI standard. Many implementations provide a Raw Mode for monitoring and capture purposes, or for new protocol development. Implementations that do not provide LLC Type 2 directly often provide an LLC2 Mode which is useful to avoid full Raw Mode when LLC Type 2 is implemented by higher protocol modules. Some implementations provide a CMSA/CD Mode; other implementations default to this behaviour anyway. A few implementations provide a Fast Path mode of operation whereby upper layer network protocol modules can associate a network address with a DLSAP and provide complete link-layer header creation from a cache instead of requiring the DLPI layer to regenerate the link-layer headers for each packet transmitted. AIX has a combined LLC Type 1 (DL_CLDLS) and LLC Type 2 (DL_CODLS) data link service mode whereby both connectionless and connection-oriented service can be invoked on the same Stream. This makes use of LLC Type 2 direct support by upper layer protocol modules somewhat simplified.

OpenSS7 implements all driver modes in an attempt to be compatible with as wide a range of DLPI implementations as possible, at least at the source-compatibility level.

3.2.3.1 Promiscuous Mode

A number of DLPI implementations support a Promiscuous Mode. Promiscuous mode is directly supported by the standard DLPI specification with the DL_PROMISCON_REQ and DL_PROMISCOFF_REQ. The promiscuous mode is normally available at three levels: the physical, SAP and multicast address level. Promiscuous mode at the physical level is intended for monitoring at the physical level on the link: all messages received from the wire regardless of DLSAP are delivered to the DLS user. Promiscuous mode at the SAP level permits all messages intended for bound DLSAP, but for any SAP component in the DLSAP, are delivered to the DLS user. Promiscuous mode at the multicast address level normally means that all messages intended for any multicast address and bound SAP component will be delivered to the DLS user. By its very nature, promscuous modes are related to a connectionless data link service, DL_CLDLS.

Some implementations support all three promiscuous levels using the standard DLPI DL_PROMISCON_REQ and DL_PROMISCOFF_REQ primitives. Others required the use of implementation-specific input-output controls. Sometimes SAP level promiscous mode is implemented by binding to a special SAP value, PROMISCUOUS_SAP. Some implementations do not have a promiscuous mode at the multicast or group address level. Yet others do no provide promiscuous modes at all.

OpenSS7 supports promiscuous mode using the standard DLPI DL_PROMISCON_REQ and DL_PROMISCOFF_REQ primitives, but also supports binding to the PROMISCUOUS_SAP, activation of promicuous modes using input-output controls: primarily DLIOCSPROMISC, DLIOCGPROMISC, and activation of multicast addresses using implementation specific extensions used to enable all multicast addresses.

3.2.3.2 Raw Mode

All drivers the support the connectionless-mode data link service provide a raw mode. Drivers that do not support connectionless-mode data link service, such as AIXlink/X.25 and Solstice X.25, do not support a raw mode.

Raw Mode is a specialized mode in which the driver can be placed that permits the examination and generation of link-layer headers including MAC addresses. What it does is extend the information included in data packets delivered to the DLS User with the complete link layer headers, including the link layer addresses. Also, data packets requested by the DLS User for transmission also include the complete link-layer headers (including MAC addresses).

One of the major purposes of the raw mode has been the interfacing of networking device drivers to packet monitoring and capture libraries such as the pcap(3) library. For this application it is quite effective when combined with the promiscuous mode.

Unfortunately, this mode of operation was never standardized in the DLPI specification, and thus implementations vary. Solaris, when placed in this mode delivers packets to the DLS user with DL_DATA_IND primitives and expected DL_DATA_REQ primitives from the DLS user; AIX issues DL_UNITDATA_IND or DL_DATA_IND primitives and expects DL_UNITDATA_REQ or DL_DATA_REQ primitives; HP-UX issues DL_HP_RAWDATA_REQ primitives and expects DL_HP_RAWDATA_REQ primitives. Also, AIX, Solaris and others set the raw mode using an input-output control, see dlpi_ioctl(4); HP-UX uses a specialized dl_service_mode setting of DL_HP_RAWDLS.13

3.2.3.3 LLC2 Mode

Most implementations of DLPI that do not support ISO/IEC 8802-2 (IEEE 802.2) LLC Type 2 operation directly, support an LLC2 mode. Normally, for ISO/IEC 8802-2 (IEEE 802.2) LLC Type 1 operation, the link-layer headers including the DA/SA, DSAP/SSAP and Unnumbered Information Control Field (0x03) are stripped from the packet before it is delivered to the DLS User in a DL_UNITDATA_IND primitive. Also, when the DLS User provided data for transmission with a DL_UNITDATA_REQ primitive, the driver adds DA/SA, DSAP/SSAP and Unnumbered Information Control Field (0x03) before transmitting the packet on the wire.

For LLC Type 2 operation, it is necessary that the DLS User be able to affect the value and format of the Control Field so that the appropriate frame type can be both received and transmitted. Therefore, drivers that do not support the DL_CLDLS data link service mode, dl_service_mode, support an LLC2 Mode. When a Stream is placed into LLC2 Mode, the DLS Provider delivers and expects the control field to be part of the data payload present in the DL_UNITDATA_IND and DL_UNITDATA_REQ primitives. Other DL_CLDLS data link service mode operations are unaffected. This permits the DLS User to implement the ISO/IEC 8802-2 (IEEE 802.2) LLC Type 2 procedures within the DLS User.

Implementations that support an LLC2 Mode are: SVR4.2,14 UnixWare.15

Implementations that provide direct support in the DLPI driver for LLC Type 2 operation do not normally have an LLC2 Mode. These are: AIXlink X.25,16 HP-UX,17 Solstice X.25.18

3.2.3.4 CSMA/CD Mode

CSMA/CD Mode is a major driver operating mode that permits both EthernetII and ISO/IEC 8802-2 (IEEE 802.2) LLC operating over Ethernet media. Some older DLPI implementations required this mode to be set, otherwise, Ethernet drivers would have to run either in a pure EthernetII mode or a pure ISO/IEC 8802-2 (IEEE 802.2) mode, but not both.

OpenSS7 always runs in this mode (because Linux is set to operate in this mode for Ethernet media) and its selection is not necessary, but is automatic. The only wrinkle is for large MTU GiGE operation.

3.2.3.5 Fast Path

Fast Path is a major driver operating mode that provides for intermodule coordination between the DLPI driver and upper layer protocols. In this mode, a mechanism is provided whereby the upper layer protocol module can determine the link-layer headers for any given DLSAP. The upper layer protocol module caches these link-layer headers against the upper layer destination protocol address (e.g. IP address) and provides those link-layer headers on each DL_CLDLS message send to DLPI. Another mechanism is provided that allows the DLS provider to indicate to the upper layer protocol module whenever link-layer headers have been invalidated (for example, due to a DL_SET_PHYS_ADDR_REQ operation). Upon receiving this indication, the upper layer module refreshes its cache of link-layer headers by mapping needed DLSAP addresses again. Solaris and HP-UX provide such a Fast Path mode of operation.

OpenSS7 also provides Fast Path modes compatible with Solaris and HP-UX in support of porting STREAMS drivers, modules and applications to Linux.

3.2.3.6 Combined Mode

Often a directly provided LLC Type 2 support in the DLPI driver is cumbersome for upper layer protocol implementation that required both an LLC Type 1 access for routing protocols and an LLC Type 2 access for connections. Often, upper layer protocol implementations will use DL_CLDLS access in Raw Mode or LLC2 Mode to circumvent the issue of having to link multiple Streams for a single upper layer service. AIX, however, provides a combined connectionless and connection-oriented mode to solve this issue using DLPI. In this mode, a Stream operates in both DL_CLDLS and DL_CODLS modes simultaneously, permitting a single DLPI Stream to provide both connectionless routing protocols as well as connection-oriented protocol connections.

In support of porting AIX DLPI drivers, modules and applications to Linux, OpenSS7 provides support for this combined connectionless and connection-oriented mode.


3.3 Primitives

Normally, DLPI implementations are based on the standard set of DLPI primitives.19 Most implementations provide a subset of the management primitives, and connectionless mode DLPI primitives. This is usually sufficient to represent MAC (Ethernet LAN) devices and ISO/IEC 8802-2 (IEEE 802.2) LLC Type 1 devices. Some implementations also provide for connection-oriented mode DLPI primitives, normally in support of ISO/IEC 8802-2 (IEEE 802.2) LLC Type 2 devices. Most implementations provide optional add-on softtware that uses connection-oriented mode DLPI primitives in support of ISO/IEC 8208 (X.25) LAPB devices. Several implementations also provide extension primitives that support specific management or extend the features of the DLPI.

AIX, AIXlink/X.25, IRIX, OSF, PowerMAX, Solstice X.25 and SVR4.2 do not document any extension primitives for DLPI.

HP-UX documents a number of general purpose management support extension primitives for DLPI, as well as a set of connection-oriented mode DLPI extension primitives designed to explicitly support management of ISO/IEC 8802-2 (IEEE 802.2) LLC Type 2 connections. Solaris documents a number of general purpose management support extension primitives for DLPI, as well as a number of Solaris feature-specific DLPI extension primitives. UnixWare documents a number of management support extension primitives for DLPI.

OpenSS7 supports all standard DLPI primitives and many extension primitives provided by other implementations, HP-UX, Solaris and UnixWare, for compatibilty and to ease porting of STREAMS DLPI drivers, modules and applications programs to Linux Fast-STREAMS.

Each porting section includes a discussion of the supported standard DLPI primitives and the extension primitives provided by each of the implementations, and how the equivalent primitives can be best used when porting DLPI applications to Linux Fast-STREAMS. Unfortunately, because the ordinal values of extension primitives are not readily available, extension primitives are source-compatible only.


3.4 Driver Input-Output Controls

Although the ability to perform input-output controls is always provided in conjunction with STREAMS drivers, the DLPI standards do not define or standardize on any input-output controls for DLPI. As a result, almost all implementations of DLPI provide management and other input-output controls that are completely implementation-specific and not generic in any way. Some implementations may provide for generic input-output controls across various DLS providers within the same operating systems, however, these is only one case of which the author is aware that the input-output controls of two implementations match in function and name (probably from BSD deriviation): that is the DL_IOC_HDR_INFO input-output control. This input-output control is shared by both Solaris and HP-UX.

Some implementations, such as Solaris and Solstice X.25, or AIX and AIXlink/X.25, define a different set of input-output controls for non-X.25 or connectionless mode providers that are provided by X.25 or connection-oriented mode DLS providers.

Some implemetnations, such as AIX, and Solaris, provide a set of input-output controls that support add-on libraries for use by DLPI applications.

The closest set of input-output controls that are common across a number of implementations are those provided originally by SVR4.2. This set is the DLIOC set of input-output controls. This set of input-output controls, or subsets of this set, appear to be supported by IRIX, PowerMAX, SVR4.2, UnixWare 1 and 2, but appear to have been dropped by UnixWare 7.

OpenSS7 provides a set of input-output controls that includes all of the documented input-output from intended porting sources, including those in supported of add-on applications libraries. Unfortunately, because the ordinal values of input-output control is not readily available, input-output controls are, for the most part, source-compatible only. Also, OpenSS7 provides an additional set of OpenSS7-specific input-output controls intended on easing the development of SNMP and CMIP management agents under Linux Fast-STREAMS.

See the input-output controls section under the porting topic for each of these implementations for more information.


3.5 Device Drivers and Modules

3.5.1 Driver Organization

Most DLPI implementations provide for two models of device driver organization:

  1. The first organization consists of a monolithic device drivers that implements both the lower level device driver functions (e.g., interrupt service routines, interacting with hardware) as well as the interface functions (passing of DLPI primitives).

    Under this organization, writing a new device driver consists of writing a complete monolithic STREAMS driver.

  2. The second organization consists of a device driver separated into a top-half and a bottom-half. The top-half is concerned with the passing of DLPI primitives with the user of the Stream and can be largely generic, and certainly not device-specific. The bottom-half is concerned with the interaction with the hardware and is device specific.

    Under this organization it is possible to write a new bottom-half for a specific device without the need to write a new top-half nor to become involved with many STREAMS specifics.

AIX uses the monolithic device driver approach, as does AIXlink/X.25. HP-UX provides the separated driver approach. Solaris provides both a separated driver approach and a monolithic driver approach. Solstice X.25 provides a monolithic driver approach.

OpenSS7 provides both a separated and monolithic driver approach. However, the separated approach is different than that of HP-UX or Solaris, and more closely related to that of OSF. In the Linux Fast-STREAMS approach, the bottom-half of the device drivers is the Linux native device driver implementation. The top-half of the driver provides access to Linux native device drivers using a generic DLPI layer. Under the monolithic approach, Linux Fast-STREAMS provides the ability to develop a device driver using either the DLPI or the CDI interfaces.

3.5.2 Driver Abstraction

Regardless of specific device driver organization, some implementations provide a mechanism whereby disparate device drivers can be accessed through a single pseudo-device (and sometimes multiplexing) driver.

This device driver abstraction can is acheived in several ways:

  1. through use of a generic top-half/bottom-half device driver construction, where the top-half of the device driver is common to all device drivers;
  2. through the use of add-on libraries that insulate the device user from the disparate access methods of various underlying drivers; or,
  3. through the provision of a multiplexing pseudo-device driver that collects all device drivers under a single multiplexing driver.

AIX uses the add-on library approach with one wrinkle: the device drivers must implement a common set of input-output controls to support the generic data link control libraries. AIXlink/X.25 does not provide generic access to the data links it provides.

HP-UX uses the top-half/bottom-half approach, and a single dlpi device driver is used to access all devices on the system.

Solaris uses a multiplexing driver to collect the disparate access methods of, for example, MAC and LLC Type 1 device drivers. Solstice X.25 does not provide generic access to the data links it provides.

OpenSS7 provides a single pseudo-device driver that both provides access to Linux native devices as well a permitting monolithic organization device Streams providing either the CDI or DLPI interfaces to be linked under the multiplex driver and provided to DLS users in the same fashion as Linux native devices. Also, the driver permits these CDI or DLPI devices to be provided for use by Linux native applications.

Specific driver and device names provided by the various implementations are detailed in the specific porting section.

3.5.3 Modules

Nearly all of the implementations provide two ipso-facto standard modules for use with DLPI device drivers:

bufmod(4)

The buffer module is used to collect many packets into a single data transfer to user space. It is particularly useful when used with a DLPI driver in raw mode and when in promiscuous mode, to group individual packets into blocks.

pfmod(4)

The packet filter module is used to filter packets arriving on a DLPI stream, particularly in raw or promiscuous modes, to reduce the number of packets delivered to user space to the minimum number of packets in which the application is interested.

OpenSS7 provides these two ipso-facto standard STREAMS modules. It also provides some useful modules not found in other implementations.

Specific module names provided by the various implementations are detailed in the specific porting section.


3.6 Support and Add-On Libraries

DLPI was intended to be used by applications programs directly using the getpmsg(2s), putpmsg(2s), read(2s), write(2s), and ioctl(2s) system calls and the interface definitions found in the sys/dlpi.h header file. Nevertheless, some implementations have provided user shared-object add-on libraries for use by DLPI applications programs that hide some of the more mundane tasks from the DLPI application programmer, and provide a functional, rather than system call, interface to DLPI DLS providers.

AIX provides a Generic Data Link Control (GDLC) interface that can be used by applications programs to access DLS providers using a common set of functions and structures. AIXlink/X.25 does not provide applications program shared-object add-on libraries.

HP-UX does not provide shared-object add-on libraries for use with DLPI.

Solaris, receently, has provided a libdlpi shared-object add-on library that provides a functional interface to the DLPI in a way similar to the way that the XTI Library provides a functional interface to the TPI. Solstice X.25 provides several libraries whose functions are intended on providing access to management and addressing information for the DLS user and are not used to directly interface to DLPI.

OpenSS7 provides all of the libraries provided by the others implementations with a set of libraries that are implemented to be compatible with their porting source equivalents.

See the libraries sub-section in each of the specific porting sections for more information on libraries.


3.7 Support and Management Utilities

All implementations provide some C-language programs and shell scripts for use in configuring, managing and trouble-shooting the implementation. Most of these programs are intended on being used from the command line or by shell scripts. One such program common to all implementations is the snoop(8) utility.

Although some utilities such as snoop(8) are common, AIX, AIXlink/X.25, HP-UX, Solaris and Solstice X.25 each provide their own set of utilities.

As with STREAMS utilities, OpenSS7 provides as many of these utilities as can be implemented using the available documentation for the utility.

See the utilities sub-section in each of the specific porting sections for more information on utilities.


3.8 Device and Driver Management

Most implementations support management of the DLPI implementation using the Simple Network Management Protocol (SNMP) of the IETF, using IETF-defined MIBs specific to each device class. No implementations currently document support for CMIP management.

OpenSS7 provides for SNMP management of the DLPI implementations using IETF MIBs, OpenSS7 Enterprise-specific MIBs, and CMIP management of the DLPI implementations using ISO/IEC GDMOs.

See the management sub-section in each of the specific porting sections for more information on management.


4 Porting from DLPI

This section includes general porting information when porting STREAMS drivers or modules, or DLPI applications from any environment supporting the DLPI to Linux Fast-STREAMS.

Use this section if you are porting from an environment other than those provided in the separate porting chapters, and when the environment from which you are porting does not closely match those for which directly support is provided in later chapters.


4.1 DLPI Driver Addressing


4.1.1 DLPI Driver Naming


4.1.2 DLPI PPA Selection

Some implementations provide a Style 2 DLS provider, some a Style 1 one. Style 2 DLPI Streams must be attached to a PPA before they can be used any further. Style 1 DLPI Streams are immediately available for use without attachment.

To determine whether the open Stream is a Style 1 or Style 2 provider, the DL_INFO_REQ primitive can be issued and the responding DL_INFO_ACK primitive examined. The dl_provider_style field contains DL_STYLE1 if the Stream is a Style 1 Stream that does not require attachemtn. When the field contains DL_STYLE2, the Stream is a Style 2 provider that requires attachment before use.


4.1.3 DLPI SAP Addressing


4.1.4 DLPI Primitive Addresses


4.1.5 DLPI Quality of Service Parameters

Most implementations of DLPI do not support quality of service parameters. OpenSS7 supports the standard DLPI quality of service parameters DL_QOS_CL_RANGE1, DL_QOS_CO_SEL1, DL_QOS_CL_RANGE1 and DL_QOS_CO_SEL1. If your implementation of DLPI supports quality of service parameters and those parameters are different from the standard DLPI quality of service parameters, they will need to be converted to the standard structure types and exchanges in primitives described by the DLPI standard.

Note that when DL_AUTO_XID and DL_AUTO_TEST flags are set in the dl_xidtest_flg field of the DL_BIND_REQ primitive, OpenSS7 DLPI drivers will perform any necessary XID or TEST DLPDU exchanges that are necessary to negotiate end-to-end parameters. Otherwise, available ranges are established by local management.


4.2 DLPI Driver Features


4.2.1 DLPI LAN Operation

4.2.1.1 DLPI Ethernet and SNAP Operation

4.2.1.2 DLPI LLC Type 1 Operation

4.2.1.3 DLPI LLC Type 2 Operation

4.2.1.4 DLPI LLC Type 3 Operation


4.2.2 DLPI WAN Operation


4.2.3 DLPI Driver Modes

4.2.3.1 DLPI Promiscuous Mode

Most implementations of DLPI support promiscious mode. Normally, the supported primitives DL_ATTACH_REQ, DL_BIND_REQ, DL_SUBS_BIND_REQ, DL_ENABMULTI_REQ, define the interface, physical address and broadcast address (MAC), service access point (SAP), subsequent service access point (SAP), and multicast or group addresses (MAC), for which packets are delivered to the DLS User. The promisuous mode primitives, DL_PROMISCON_REQ, DL_PROMISCOFF_REQ, act to provide a promiscous wildcard at various points in the link layer header defined by the foregoing primitives.

When DL_PROMISC_PHYS is specified, the Stream becomes promiscuous at the physical level. This means that all packets on the wire associated with the interface identified by the attached PPA will be indicated to the DLS User. This is the case regardless of the setting of the other promicious levels.

When DL_PROMISC_SAP is specified, the Stream becomes promiscuous at the SAP level. This means that all packets on the wire that match the physical address, and enabled broadcast, multicast or group addresses,20 regardless of the SAP that was bound with DL_BIND_REQ or DL_SUBS_BIND_REQ, will be delivered to the DLS User. This promiscuous level being set has no effect when DL_PROMISC_PHYS is also set.

When DL_PROMISC_MULTI is specified, the Stream becomes promiscuous at the broadcast, multicast and group address level. This means that all packets on the write that match the physical address, and any broadcast, multicast or group address, regardless of the addresses that have been enabled with DL_ENABMULTI_REQ, and matches enabled SAP for the Stream,21 will be delivered to the DLS User. This promiscuous level being set has no effect when DL_PROMISC_PHYS is also set.

4.2.3.2 DLPI Raw Mode

Most implementations of DLPI support a raw mode. The purpose of a raw mode is largely to permit monitoring applications, but also to permit the implementation of protocols not anticipated by the DLPI specifications. In raw mode, link-layer headers are not removed from the data payload of messages delivered to the DLPI User. Also, link-layer headers are not added by the DLS Provider to DLS User data submitted for transmission. This means that not only does the DLS User need to interpret link-layer headers on received messages itself, but it needs to create appropriate link-layer headers for any messages for transmission.

Raw mode is normally invoked with an input-output control. AIX and Solaris place a DLPI Stream into raw mode using an implemetnation-specific input-output control. HP-UX, in constrast, provides an implementation-specific value for the dl_service_mode member of the DL_BIND_REQ primitive, DL_HP_RAWDLS, that places a DLPI Stream into raw mode.

Once in raw mode, some implementations differ in how raw packets are delivered to the DLS User.

For Solaris, when placed into raw mode, packets are delivered to the DLS User using DL_DATA_IND primitives. Packets sent by the DLS User are expected to be DL_DATA_REQ primitives.

For AIX, when placed into raw mode, packets are delivered to the DLS User using DL_UNITDATA_IND primitives, however, the primitive contains no address fields and may be removed for AIX at some point, after which packets will be delivered to the DLS User using DL_DATA_IND primitives. Packets sent by the DLS User are expected to be DL_UNITDATA_REQ primitives containing no address or DL_DATA_REQ primitives.

For HP-UX, when placed into raw mode, packets are delivered to the DLS User using DL_HP_RAWDATA_IND extension primitives. Packets sent by the DLS User are expected to be DL_HP_RAWDATA_REQ extension primitives.

4.2.3.3 DLPI LLC2 Mode

LLC2 mode is a mode provided primarily by systems that do not support the DLPI connection-oriented mode. It allows the DLS User to include control octets in the data payload. Otherwise, LLC data would normally be sent by a DL_CLDLS DLS provider as an Unnumbered Information (UI) frame.

4.2.3.4 DLPI CSMA/CD Mode

4.2.3.5 DLPI Fast Path

4.2.3.6 DLPI Combined Mode


4.3 DLPI Primitives

In some cases provided by the DLPI standard, the primitive interface may be unsuitable in comparison to the input-output control interface. Under STREAMS, the identity of, and permissions afforded, the user passing the M_PROTO or M_PCPROTO primitive to the Stream are not provided by the put message, putpmsg(2s), system call. On the other hand, the input-output control, ioctl(2s), system call both identifies and provides permissions for the invoking user. DLPI primitives of concern in this regard are:

Another approach is to not permit processes with insufficient privilege to open the DLPI driver in the first place. How this problem or issue is dealt with by specific implementations has an impact on the portability of DLPI applications programs.

DL_ATTACH_REQ

Of primary concern to porting is the specification of the dl_ppa field in this primitive. DLS providers are allowed to manage their own Physical Point of Attachment (PPA) space in implementation specific manners. DLPI cautions applications to obtain the PPA from passed in arguments or a management call and pass the PPA opaquely to DLPI. This is not always the case. Also, unfortunately the management subroutines available to the application for this purpose are nowhere standardized.

DL_BIND_REQ
DL_SUBS_BIND_REQ
DL_DATA_REQ
DL_DATA_IND
DL_UNITDATA_REQ
DL_UNITDATA_IND
DL_PROMISCON_REQ
DL_PROMISCOFF_REQ

Not all implementations nor all DLS providers support these primitives. This does not mean that they do not support promiscuous modes on these devices, it just means that some other mechanism is used to place devices in promiscuous mode and to detect that they are in promiscous mode.

Normally these primitives are supported for DLS providers with a MAC type of DL_ETHER.

DL_ENABMULTI_REQ
DL_DISABMULTI_REQ

Not all implementations nor all DLS provider support these primitives. This does not mean that they do not support multicast addresses on these devices, it just means that some other mechanism is used to manage multicast addresses on these devices.


4.4 DLPI Input-Output Controls

Input-Output Control are not standardized. However, most implementations provide some sort of input-output control that performs the following functions:


4.5 DLPI Drivers and Modules


4.6 DLPI Libraries


4.7 DLPI Utilities


4.8 DLPI Management


4.9 DLPI Summary


5 Porting from AIX

This section is applicable to later releases of the AIX operating system which is IBM’s UNIX System V Release 4 derived version of the UNIX operating system. DLPI is documented primarily in the “Communications Programming Concepts, Chapter 2, Data Link Provider Interface Implemetnation” and the “Technical Reference: Communications, Volume 1, Chapter 2, Data Link Provider Interface (DLPI)” documentation for the AIX operating system. Use this section when porting DLPI drivers, modules and applications from base AIX to Linux.


5.1 AIX Driver Addressing

The AIX implementation of the DLPI interface provides a Style 2 DLS provider that supports both connectionless, DL_CLDLS, and connection-oriented, DL_CODLS, data link service modes. AIX also supports a combined connectionless and connection-oriented mode: see, AIX Combined Mode.


5.1.1 AIX Driver Naming


5.1.2 AIX PPA Selection


5.1.3 AIX SAP Addressing


5.1.4 AIX Primitive Addresses


5.1.5 AIX Quality of Service Parameters


5.2 AIX Driver Features


5.2.1 AIX LAN Operation

5.2.1.1 AIX Ethernet and SNAP Operation

5.2.1.2 AIX LLC Type 1 Operation

5.2.1.3 AIX LLC Type 2 Operation

5.2.1.4 AIX LLC Type 3 Operation


5.2.2 AIX WAN Operation


5.2.3 AIX Driver Modes


5.2.3.1 AIX Promiscuous Mode

AIX supports a promiscuous mode using the standard DLPI primitives, DL_PROMISCON_REQ and DL_PROMISCOFF_REQ. AIX supports all three promiscuous levels, DL_PROMISC_PHYS, DL_PROMISC_SAP and DL_PROMISC_MULTI, for these primitives. There are some minor compatibility issues with the DL_PROMISCON_REQ primitive (see AIX DL_PROMISCON_REQ).


5.2.3.2 AIX Raw Mode

AIX supports a raw mode. Setting a DLPI Stream to raw mode consists of using the DL_PKT_FORMAT input-output control to set the packet format for the Stream to NS_INCLUDE_MAC. When set to raw mode, the MAC and LLC link-layer headers are both placed in the data portion of the message.

Messages delivered to the DLS user are delivered as DL_UNITDATA_IND primitives, but at some point might be restricted to DL_DATA_IND primitives (i.e. just the M_DATA message block). DLS Users should be prepared to receive both. Both can be handled easily by simply discarding any M_PROTO message block containing a DL_UNITDATA_IND primitive and only only processing the attached M_DATA message block.

Messages sent to the DLS provider may be sent as DL_UNITDATA_REQ primitives, but at some point might be restricted to DL_DATA_REQ primitives (i.e. just the M_DATA message block). DLS Users should be prepared to send either. The destination address fo the DL_UNITDATA_REQ message block must be completed as normal, however, it is not used to create a link-layer header for the final message, and the attached M_DATA message block must contain the link-layer header including the MAC addresses.

OpenSS7 provides full source-level compatibility with this mode by providing a source-compatible DL_PKG_FORMAT input-output control that accepts the NS_INCLDUE_MAC format. When the raw format is set using this input-output control, an AIX compataible raw mode is applied to the Stream.


5.2.3.3 AIX LLC2 Mode

AIX supports an LLC2 mode. Setting a DLPI Stream to LLC2 mode consists of using the DL_PKG_FORMAT input-output control to set the packet format for the Stream to NS_INCLUDE_LLC. When set to LLC2 mode, the LLC link-layer headers are placed in the data portion of the message. Only the MAC addresses are removed or inserted when messages are received or transmitted on the media.

Messages delivered to the DLS user are delivered as DL_UNITDATA_REQ primitives. The LLC link-layer headers are included in the M_DATA portion of the primitive. The destination and source addresses contained in the M_PROTO portion of the DL_UNITDATA_IND primtive contain only the MAC address and do not contain the DSAP, SSAP or SNAP portion.

Messages sent to the DLS provider are sent as DL_UNITDATA_REQ primitives. The M_DATA portion of the primitive must contain the LLC link-layer headers. The destination and source addresses contained in the M_PROTO portion of the DL_UNITDATA_REQ primitive contain only the MAC address and do not contain the DSAP, SSAP or SNAP portion.

OpenSS7 provides full source-lvel compatibility with this mode by providing a source-compatible DL_PKG_FORMAT input-outpu control that accepts the NS_INCLUDE_LLC format. When the LLC format is set using this input-output control, an AIX compatible LLC2 mode is applied to the Stream.


5.2.3.4 AIX CSMA/CD Mode


5.2.3.5 AIX Fast Path

AIX does not provide fast path.


5.2.3.6 AIX Combined Mode

AIX extends the standard DLPI specification by permitting both DL_CLDLS and DL_CODLS to be specified in the dl_service_mode field of the DL_BIND_REQ primitive by logically OR’ing the two values together. (The DL_CLDLS, DL_CODLS and DL_ACLDLS values may be logically OR’ed together in the dl_service_mode field of the DL_INFO_ACK primitive.) Once the bind has completed in this manner, both connectionless and connection-oriented messages can be exchanged for the Stream.


5.3 AIX Primitives

AIX widely supports connectionless and connection-oriented DLIP standard primitives and provides no extension primitive. Minor extensions are provided by extending some of the standard DLPI primitives. Other extensions are provided with implementation-specific input-output controls.


5.3.1 AIX Supported Primitives

The following primitives are supported by AIX:

The following XID and TEST primitives are supported by AIX:

The following connectionless mode primitives are supported by AIX:

The following connection-oriented mode primitives are supported by AIX:


5.3.2 AIX Unsupported Primitives

The following primitives are not supported by AIX:

The following acknowledged connectionless mode primitives are not supported by AIX:


5.3.3 AIX Extension Primitives

AIX does not provide any extension primitives.


5.4 AIX Input-Output Controls

AIX provides a number of implementation-specific input-output controls that are defined in the sys/dlpi_aix.h header file. Input-output controls that take an argument longer than a small integer or that take a pointer to a buffer are required to use the I_STR(7) (see streamio(7)) STREAMS input-output control (however, OpenSS7 also supports transparent input-output controls).

Implementation-specific input-output controls provided by AIX are as follows:

DL_PKT_FORMATset the packet format.
DL_INPUT_RESOLVEregister input address resolution callback.
DL_OUTPUT_RESOLVEregister output address resolution callback.
DL_ROUTEdisable, query or assign a source route.
DL_TUNE_LLCquery or alter tunable LLC parameters.
DL_ZERO_STATSreset local or global statistics.
DL_SET_REMADDRset remote address for XID/TEST.

Note that OpenSS7 documents these input-output controls in detail in the dlpi_ioctl(4) manual page.


5.5 AIX Drivers and Modules


5.6 AIX Libraries


5.7 AIX Utilities


5.8 AIX Management


5.9 AIX Summary


6 Porting from AIXlink/X.25


6.1 AIXlink/X.25 Driver Addressing


6.1.1 AIXlink/X.25 Driver Naming


6.1.2 AIXlink/X.25 PPA Selection


6.1.3 AIXlink/X.25 SAP Addressing


6.1.4 AIXlink/X.25 Primitive Addresses


6.1.5 AIXlink/X.25 Quality of Service Parameters


6.2 AIXlink/X.25 Driver Features


6.2.1 AIXlink/X.25 LAN Operation

6.2.1.1 AIXlink/X.25 Ethernet and SNAP Operation

6.2.1.2 AIXlink/X.25 LLC Type 1 Operation

6.2.1.3 AIXlink/X.25 LLC Type 2 Operation

6.2.1.4 AIXlink/X.25 LLC Type 3 Operation


6.2.2 AIXlink/X.25 WAN Operation


6.2.3 AIXlink/X.25 Driver Modes

6.2.3.1 AIXlink/X.25 Promiscuous Mode

AIXlink/X.25 does not support promiscuous mode and does not support the DL_PROMISCON_REQ or DL_PROMISCOFF_REQ primitives.

6.2.3.2 AIXlink/X.25 Raw Mode

AIXlink/X.25 does not support a raw mode.

6.2.3.3 AIXlink/X.25 LLC2 Mode

AIXlink/X.25 does not support an LLC2 mode.

6.2.3.4 AIXlink/X.25 CSMA/CD Mode

6.2.3.5 AIXlink/X.25 Fast Path

6.2.3.6 AIXlink/X.25 Combined Mode


6.3 AIXlink/X.25 Primitives

6.3.1 AIXlink/X.25 Supported Primitives

The following primitives are supported by AIXlink/X.25:

DL_BIND_REQ
DL_BIND_ACK
DL_ERROR_ACK
DL_INFO_REQ
DL_INFO_ACK
DL_OK_ACK
DL_UNBIND_REQ

The following connection-oriented mode primitives are supported by AIXlink/X.25:

DL_CONNECT_REQ
DL_CONNECT_CON
DL_DISCONNECT_REQ
DL_DISCONNECT_IND
DL_RESET_REQ
DL_RESET_IND
DL_RESET_RES
DL_RESET_CON

6.3.2 AIXlink/X.25 Unsupported Primitives

The following primitives are not supported by AIXlink/X.25:

The following XID and TEST primitives are not supported by AIXlink/X.25:

The following connection-oriented mode primitives are not supported by AIXlink/X.25:

The following connectionless mode primitives are not supported by AIXlink/X.25:

The following acknowledged connectionless mode primitives are not supported by AIXlink/X.25:

6.3.3 AIXlink/X.25 Primitive Porting Considerations

6.3.4 AIXlink/X.25 Extension Primitives

AIXlink/X.25 does not provide any extension primitives.


6.4 AIXlink/X.25 Input-Output Controls

See dlpi_ioctl(4) for more detail.


6.5 AIXlink/X.25 Drivers and Modules


6.6 AIXlink/X.25 Libraries


6.7 AIXlink/X.25 Utilities


6.8 AIXlink/X.25 Management


6.9 AIXlink/X.25 Summary


7 Porting from HP-UX


7.1 HP-UX Driver Addressing


7.1.1 HP-UX Driver Naming


7.1.2 HP-UX PPA Selection


7.1.3 HP-UX SAP Addressing


7.1.4 HP-UX Primitive Addresses


7.1.5 HP-UX Quality of Service Parameters


7.2 HP-UX Driver Features


7.2.1 HP-UX LAN Operation

7.2.1.1 HP-UX Ethernet and SNAP Operation

7.2.1.2 HP-UX LLC Type 1 Operation

7.2.1.3 HP-UX LLC Type 2 Operation

7.2.1.4 HP-UX LLC Type 3 Operation


7.2.2 HP-UX WAN Operation


7.2.3 HP-UX Driver Modes

7.2.3.1 HP-UX Promiscuous Mode

7.2.3.2 HP-UX Raw Mode

HP-UX provides support for a raw mode where the link-layer headers and included in packets both delivered to the DLS User and accepted from the DLS User. The HP-UX raw mode is entered by setting the dl_service_mode field of the DL_BIND_REQ primitive to DL_HP_RAWDLS.

When raw mode has been enabled, all packets delivered to the DLS User are delivered as DL_HP_RAWDATA_IND primitives; all packets accepted from the DLS User are DL_HP_RAWDATA_REQ primitives.

This approach differs from other approaches in several ways:

OpenSS7 supports the HP-UX DL_HP_RAWDLS service mode as well as the DL_HP_RAWDATA_IND and DL_HP_RAWDATA_REQ primitives in support of the porting of DLPI drivers, modules and applications programs from HP-UX to Linux.

7.2.3.3 HP-UX LLC2 Mode

LLC2 mode is a mode provided primarily by systems that do not support the DLPI connection-oriented mode. It allows the DLS User to include control octets in the data payload. Otherwise, LLC data would normally be sent by a DL_CLDLS DLS provider as an Unnumbered Information (UI) frame.

HP-UX supports LLC2 directly using the DLPI driver and, therefore, does not require an LLC2 mode.

OpenSS7 also supports LLC2 directly using the DLPI driver permitting DLPI drivers, modules and applications to be ported from HP-UX to Linux without the need for an LLC2 mode.

7.2.3.4 HP-UX CSMA/CD Mode

7.2.3.5 HP-UX Fast Path

7.2.3.6 HP-UX Combined Mode


7.3 HP-UX Primitives

7.3.1 HP-UX Supported Primitives

The following primitives are supported by HP-UX:

The following connectionless mode primitives are supported by HP-UX:

The following connection-oriented mode primitives are supported by HP-UX:

7.3.2 HP-UX Unsupported Primitives

The following primitives are not supported by HP-UX:

The following acknowledged connectionless mode primitives are not supported by HP-UX:

7.3.3 HP-UX Primitive Porting Considerations

DL_PROMISCON_REQ

OpenSS7 supports this primitive being issued multiple times by the DLS users for the same promiscuous level without generating a fatal or non-fatal error. HP-UX documentation is silent on the matter.

Care should be taken when porting HP-UX drivers, modules and applications to OpenSS7 that the DLS user does not rely upon the DLS provider returning an error should this primitive be issued multiple times for the same promiscuous level.

DL_PROMISCOFF_REQ

OpenSS7 supports this primitive being issued multiple times by the DLS users for the same promiscuous level without generating a fatal or non-fatal error. HP-UX documentation is silent on the matter.

Care should be taken when porting HP-UX drivers, modules and applications to OpenSS7 that the DLS user does not rely upon the DLS provider returning an error should this primitive be issued multiple times for the same promiscuous level.

7.3.4 HP-UX Extension Primitives

HP-UX provides the following extension primitives:

DL_HP_GET_64BIT_STATS_ACK
DL_HP_GET_64BIT_STATS_REQ
DL_HP_HW_RESET_REQ
DL_HP_LINK_DOWN_IND
DL_HP_LINK_UP_IND
DL_HP_MULTICAST_LIST_ACK
DL_HP_MULTICAST_LIST_REQ
DL_HP_NOTIFY_EVENT_REQ
DL_HP_PPA_ACK
DL_HP_PPA_REQ
DL_HP_RAWDATA_IND
DL_HP_RAWDATA_REQ
DL_HP_RESET_STATS_REQ

HP-UX provides the following connection-oriented mode extension primitives:

DL_HP_CLEAR_LOCAL_BUSY_REQ
DL_HP_CLEAR_STATS_REQ
DL_HP_INFO_ACK
DL_HP_INFO_REQ
DL_HP_SET_ACK_THRESHOLD_REQ
DL_HP_SET_ACK_TO_REQ
DL_HP_SET_BUSY_TO_REQ
DL_HP_SET_LOCAL_BUSY_REQ
DL_HP_SET_LOCAL_WIN_REQ
DL_HP_SET_MAX_RETRIES_REQ
DL_HP_SET_P_TO_REQ
DL_HP_SET_REJ_TO_REQ
DL_HP_SET_REMOTE_WIN_REQ
DL_HP_SET_SEND_ACK_TO_REQ

7.4 HP-UX Input-Output Controls

See dlpi_ioctl(4) for more detail.


7.5 HP-UX Drivers and Modules


7.6 HP-UX Libraries


7.7 HP-UX Utilities


7.8 HP-UX Management


7.9 HP-UX Summary


8 Porting from IRIX

IRIX is the UNIX System V Release 4.2 based operating system which is a product of Silicon Graphics Inc., or just SGI.


8.1 IRIX Driver Addressing


8.1.1 IRIX Driver Naming


8.1.2 IRIX PPA Selection


8.1.3 IRIX SAP Addressing

Directly from the IRIX manual page:22

The normal mode of operation is when a bind, DL_BIND_REQ, is performed with the value of the SAP, dl_sap, information being in the rante 0x02 to 0xFE, inclusive (one-octet, even-value). This is the same as specified under ISO/IEC 8802-2 (IEEE 802.2) LLC, and is the onl mode of operation fro connection-oriented (i.e. LLC Type 2) service mode. The Sub-Network Access Protocol (SNAP) als uses this mode of operation. The DLSAP address for normal mode has the following format:

struct llc_dlsap {
    u_char dl_mac[6];  /* hardware address */
    u_char dl_sap;     /* LLC SAP */
};

The DLSAP address may be modified through DL_SUBS_BIND_REQ primitive when the SNAP is used to extend the LLC header. The extended SNAP DLSAP addresse have the following format:

struct llc_snap_dlsap {
    u_char dl_mac[6];    /* hardware address */
    u_char dl_sap;       /* SNAP sap: 0xAA */
    u_char dl_oui[3];    /* OUI information */
    u_char dl_proto[2];  /* protocol ID */
};

DLS users should use the llc_dlsap format in constructing the DL_UNITDATA_REQ primitive and it is the DLS User responsibility to put the OUI information and protocol ID in front of their data. Upon receipt of DL_UNITDATA_IND, the DLSAP addresses are also of llc_dlsap format. It is the DLS User responsibility to skip the OUI information and protocol ID for the user data.

The DLSAP address may also be modified if source routing is used for Token Ring networks through TEST and/or XID primitives. The source routing information field (rif) is appended to the end of the llc_dlsap format. The DL_CONNECT_REQ, DL_CONNECT_IND, DL_CONNECT_RES, DL_CONNECT_CON, primitives should also use this llc_sri_dlsap format when source routing information is present. The extended SRI DLSAP addresses have the following format:

struct llc_sri_dlsap {
    u_char dl_mac[6];    /* hardware address */
    u_char dl_sap;       /* LLC SAP */
    u_char dl_rif;       /* start of rif */
};

The Ethernet mode of operation occurs when a bind is performed for two bytes (the high byte being non-zero). When this occurs, the binding driver will be sent packets for the Ethernet types registered for.

The DLSAP address for Ethernet mode has the following format:

struct llc_eth_dlsap {
    u_char dl_mac[6];    /* hardware address */
    u_short dl_sap;      /* Ethernet SAP */
};

8.1.4 IRIX Primitive Addresses


8.1.5 IRIX Quality of Service Parameters


8.2 IRIX Driver Features


8.2.1 IRIX LAN Operation

8.2.1.1 IRIX Ethernet and SNAP Operation

8.2.1.2 IRIX LLC Type 1 Operation

As will all of the other implementations, LLC Type 1 operation is supported.

8.2.1.3 IRIX LLC Type 2 Operation

IRIX is another of the implementations that supports LLC Type 2 directly, using the DL_CODLS data link service and the associated connection-oriented mode service primitives.

8.2.1.4 IRIX LLC Type 3 Operation

IRIX does not support LLC Type 3, as is true for the other UNIX implementations.


8.2.2 IRIX WAN Operation


8.2.3 IRIX Driver Modes

8.2.3.1 IRIX Promiscuous Mode

8.2.3.2 IRIX Raw Mode

8.2.3.3 IRIX LLC2 Mode

LLC2 mode is a mode provided primarily by systems that do not support the DLPI connection-oriented mode. It allows the DLS User to include control octets in the data payload. Otherwise, LLC data would normally be sent by a DL_CLDLS DLS provider as an Unnumbered Information (UI) frame.

IRIX supports LLC2 directly using the DLPI driver and, therefore, does not require an LLC2 mode.

OpenSS7 also supports LLC2 directly using the DLPI driver permitting DLPI drivers, modules and applications to be ported from IRIX to Linux without the need for an LLC2 mode.

8.2.3.4 IRIX CSMA/CD Mode

8.2.3.5 IRIX Fast Path

8.2.3.6 IRIX Combined Mode


8.3 IRIX Primitives

8.3.1 IRIX Supported Primitives

The following primitives are supported by IRIX:

DL_INFO_REQ
DL_INFO_ACK
DL_ERROR_ACK
DL_OK_ACK
DL_ATTACH_REQ
DL_DETACH_REQ
DL_BIND_REQ
DL_BIND_ACK
DL_SUBS_BIND_REQ
DL_SUBS_BIND_ACK
DL_SUBS_UNBIND_REQ
DL_ENABMULTI_REQ
DL_DISABMULTI_REQ
DL_PHYS_ADDR_REQ
DL_PHYS_ADDR_ACK
DL_SET_PHYS_ADDR_ACK
DL_XID_REQ
DL_XID_IND
DL_XID_RES
DL_XID_CON
DL_TEST_REQ
DL_TEST_IND
DL_TEST_RES
DL_TEST_CON

The following connectionless mode primitives are supported by IRIX:

DL_UNITDATA_REQ
DL_UNITDATA_IND
DL_UDERROR_IND

The following connection-oriented mode primitives are supported by IRIX:

DL_TOKEN_REQ
DL_TOKEN_ACK
DL_CONNECT_REQ
DL_CONNECT_IND
DL_CONNECT_RES
DL_CONNECT_CON
DL_DATA_REQ
DL_DATA_IND
DL_RESET_REQ
DL_RESET_IND
DL_RESET_RES
DL_RESET_CON
DL_DISCONNECT_REQ
DL_DISCONNECT_IND

8.3.2 IRIX Unsupported Primitives

The following primitives are not supported by IRIX:

The following connectionless mode primitives are not supported by IRIX:

The following acknowledged connectionless mode primitives are not supported by IRIX:

8.3.3 IRIX Extension Primitives

IRIX provides no extension primitives.


8.4 IRIX Input-Output Controls

See dlpi_ioctl(4) for more detail.


8.5 IRIX Drivers and Modules


8.6 IRIX Libraries


8.7 IRIX Utilities


8.8 IRIX Management


8.9 IRIX Summary


9 Porting from OSF

Here the reference to “OSF” refers to Digtal UNIX and Tru64 UNIX and all those other names that OSF derivatives have been called.


9.1 OSF Driver Addressing

Each DLPI user must establish an identity to communicate with other data link users. This identity consists of the following pieces of information:


9.1.1 OSF Driver Naming


9.1.2 OSF PPA Selection

Physical attachment identification identifies the physical medium over which the DLS user communicates. The importance of identifying the physical medium is particularly evident on systems that are attached to multiple physical media.

The PPA is the point at which the system attaches itself to the physical communications medium. All communication on that physical medium funnels through the PPA. On systems where DLS provider supports more than one physical medium, the DLS user must identify the medium through which it will communicate. A PPA is identified by a unique PPA identifier.

OSF only supports the Style 2 provider because it is more suitable for supporting large numbers of PPAs.

To establish a list of available PPAs, OSF provides the ND_GET input-output control. This input-output control is a general purpose I_STR(7) (see streamio(7)) input-output control that takes a buffer containing a identifier string (in this case “dl_ifnames”) and returns a output string in the same buffer. The output string looks something like:

sscc0 (PPA 1) ln0 (PPA 2) dsy9 (PPA 3) dsy1 (PPA 4) sl0 (PPA 5) sl1 (PPA 6) lo0

The ND_GET input-output control is defined as:

#define ND_GET (('N' << 8) + 0)

9.1.3 OSF SAP Addressing

The DLS user must register with the DLS provider so that the provider can deliver protocol data units destined for that user.

The format of the DLSAP address is an unsigned character array containing the Media Access Control (MAC) addresses followed by the bound Service Access Point (SAP). The SAP is usually two bytes in the case of Ethernet, or one byte in the case of ISO/IEC 8802-2 (IEEE 802.2). The one exception is when DL_HIERARCHICAL_BIND is processed. In that case, the DLSAP address consists of the MAC address, the SNAP SAP (0xAA), and a five-byte SNAP.


9.1.4 OSF Primitive Addresses

The format of the DLSAP address is an unsigned character array containing the Media Access Control (MAC) addresses followed by the bound Service Access Point (SAP). The SAP is usually two bytes in the case of Ethernet, or one byte in the case of ISO/IEC 8802-2 (IEEE 802.2). The one exception is when DL_HIERARCHICAL_BIND is processed. In that case, the DLSAP address consists of the MAC address, the SNAP SAP (0xAA), and a five-byte SNAP.


9.1.5 OSF Quality of Service Parameters

OSF does not support quality of service parameters.


9.2 OSF Driver Features


9.2.1 OSF LAN Operation

9.2.1.1 OSF Ethernet and SNAP Operation

9.2.1.2 OSF LLC Type 1 Operation

OSF dlb(7) driver supports LLC Type 1 and Ethernet operation in the usual manner.

9.2.1.3 OSF LLC Type 2 Operation

OSF is one of the DLPI implementations that does not directly support LLC Type 2 operation.

9.2.1.4 OSF LLC Type 3 Operation

OSF, as the other UNIX derivatives, does not directly support LLC Type 3 operation.


9.2.2 OSF WAN Operation


9.2.3 OSF Driver Modes

9.2.3.1 OSF Promiscuous Mode

It is unclears whether the dlb(7) driver supports promiscuous mode. OSF does not document input-output controls to place DLPI interfaces into promiscuous mode and does not support the DL_PROMISCON_REQ and DL_PROMISCOFF_REQ primitive. Chances are they recommend the sockets DLI interface instead.

9.2.3.2 OSF Raw Mode

It is unclear whether the dlb(7) driver supports an Raw Mode. OSF does not document input-output controls to place DLPI interfaces into raw mode. Chances are they recommend the sockets DLI interface instead.

9.2.3.3 OSF LLC2 Mode

Although OSF does not directly support LLC Type 2 operation, it is unclear whether the dlb(7) driver supports an LLC2 Mode. OSF does not document input-output controls to place DLPI interfaces into LLC2 mode. Chances are they recommend the sockets DLI interface instead.

9.2.3.4 OSF CSMA/CD Mode

It is unclears whether the dlb(7) driver supports CSMA/CD mode. OSF does not document input-output controls to place DLPI interfaces into CSMA/CD mode. Chances are they recommend the sockets DLI interface instead.

9.2.3.5 OSF Fast Path

OSF does not document a Fast Path. One of the reasons for this is that the OSF DLPI driver, dlb(7), is really just a bridge to the underlying BSD interfaces. Therefore, upper layer protocols within the BSD stack, such as IP, do not require a fast path from DLPI.

9.2.3.6 OSF Combined Mode

OSF does not support connection-oriented mode, far less a combined connectionless and connection-oriented mode.


9.3 OSF Primitives

9.3.1 OSF Supported Primitives

The following primitives are supported by OSF:

The following connectionless mode primitives are supported by OSF:

9.3.2 OSF Unsupported Primitives

The following primitives are not supported by OSF:

The following connectionless mode primitives are not supported by OSF:

The following connection-oriented mode primitives are not supported by OSF:

The following acknowledged-connectionless mode primitives are not supported by OSF:

9.3.3 OSF Extension Primitives

OSF does not provide any extension primitives.


9.4 OSF Input-Output Controls

OSF input-output controls are not well documented.

See dlpi_ioctl(4) for more detail.


9.5 OSF Drivers and Modules

OSF basically provides a similar type of module to that provided by OpenSS7: it is a DLPI driver that bridges between STREAMS and the underlying BSD network device interfaces that are provided by OSF’s basic BSD kernel. Therefore, the driver, dlb(7), is basically organized into a top-half and bottom-half, where the top-half is the DLPI STREAMS driver, and the BSD network device implementation is the bottom-half.

Unfortunately, OSF DLPI support is somewhat lacking compared to others. The richer interface is the sockets-based (and BSD-based) DLI interface, which is roughly equivalent to the packet-mode sockets in Linux. If you are porting a DLI application, you are in the wrong place. DLI applications should be ported to native Linux sockets rather than DLPI.


9.6 OSF Libraries

OSF does not provide any libraries or utilities (other than basic STREAMS facilities) in support of DLPI applications.


9.7 OSF Utilities

Because OSF implements a bridging driver, it provides few DLPI specific utilities and administration tools. Most of the tools that are provided are BSD-style management programs and scripts intended on maintaining the BSD networking kernel.


9.8 OSF Management

Management of the OSF networking is BSD-based and managed largely via SNMP.


9.9 OSF Summary

In general, porting OSF DLPI applications to Linux should pose little difficulty. The OSF DLPI implementations is very restricted in scope and features and any DLPI driver, module, or application should port directly to OpenSS7 without issue. All of the addressing and modes are supported buy Linux Fast-STREAMS. Special add-on packages (probably based on the Spider implemetnation) are used for X.25. See the OpenSS7 X.25 porting guide for more information.

One simplification provided by the OpenSS7 implementation is that the PPA associated with a given network interface is the same as the IETF Interface MIB ifIndex associated with that interface. It is not necessary to use the ND_GET in the fashion of OSF to collect information about the mapping of interface names to interface indices. Either the SNMP functions can be used, or the input-output controls documented in netdevice(7) can be used.


10 Porting from PowerMAX

PowerMAX OS is the SVR 4.2MP based operating system provided by Concurrent Computer Corporation.


10.1 PowerMAX Driver Addressing


10.1.1 PowerMAX Driver Naming


10.1.2 PowerMAX PPA Selection


10.1.3 PowerMAX SAP Addressing

PowerMAX provides the symbol PROMISCUOUS_SAP that once bound to acts as though DL_PROMISCON_REQ was successful at the DL_PROMISC_SAP level.


10.1.4 PowerMAX Primitive Addresses


10.1.5 PowerMAX Quality of Service Parameters


10.2 PowerMAX Driver Features


10.2.1 PowerMAX LAN Operation

10.2.1.1 PowerMAX Ethernet and SNAP Operation

10.2.1.2 PowerMAX LLC Type 1 Operation

The PowerMAX DLPI driver supports LLC Type 1 and Ethernet operation in the usual manner.

10.2.1.3 PowerMAX LLC Type 2 Operation

PowerMAX is one of the DLPI implementations that does not directly support LLC Type 2 operation. However, it does not appear to have an LLC2 Mode necessary for use by LLC2 DLS users. This might just be a documentation oversight. OpenSS7 provides the normal SVR 4.2 DLIOCLLC2MODE input-output control for setting the LLC2 Mode.

10.2.1.4 PowerMAX LLC Type 3 Operation

PowerMAX, as the other UNIX derivatives, does not directly support LLC Type 3 operation.


10.2.2 PowerMAX WAN Operation


10.2.3 PowerMAX Driver Modes

10.2.3.1 PowerMAX Promiscuous Mode

PowerMAX provides the symbol PROMISCUOUS_SAP that once bound to acts as though DL_PROMISCON_REQ was successful at the DL_PROMISC_SAP level. The input-output contol command, DLIOCSPROMISC can be used to set the Stream as promiscuous at the DL_PROMISC_PHYS level. The input-output control command, DLIOCADDMULTI can be used to set the Stream as promiscuous at the DL_PROMISC_MULTI level, but it needs to be executed once for each known multicast or group address.

10.2.3.2 PowerMAX Raw Mode

PowerMAX does not appear to have an Raw Mode. That is, it does not document the availablity of the DLIOCRAWMODE input-output control command used by SVR4.2 to toggle the Raw Mode. This might just be a documentation oversight, in which case, OpenSS7 provides one anyway.

10.2.3.3 PowerMAX LLC2 Mode

LLC2 mode is a mode provided primarily by systems that do not support the DLPI connection-oriented mode. It allows the DLS User to include control octets in the data payload. Otherwise, LLC data would normally be sent by a DL_CLDLS DLS provider as an Unnumbered Information (UI) frame.

PowerMAX does not directly support LLC Type 2 operation. Nevertheless, it does not appear to have an LLC2 Mode. That is, it does not document the availability of the DLIOCLLC2MODE input-output control command.

10.2.3.4 PowerMAX CSMA/CD Mode

PowerMAX documents that the CSMA/CD Mode can be toggled using the usual SVR 4.2 DLIOCCSMACDMODE input-output control.

10.2.3.5 PowerMAX Fast Path

PowerMAX does not document a Fast Path.

10.2.3.6 PowerMAX Combined Mode


10.3 PowerMAX Primitives

10.3.1 PowerMAX Supported Primitives

The following primitives are supported by PowerMAX:

The following connectionless mode primitives are supported by PowerMAX:

10.3.2 PowerMAX Unsupported Primitives

The following primitives are not supported by PowerMAX:

The following connectionless mode primitives are not supported by PowerMAX:

The following connection-oriented mode primitives are not supported by PowerMAX:

The following acknowledged-connectionless mode primitives are not supported by PowerMAX:

10.3.3 PowerMAX Extension Primitives

PowerMAX does not provide any extension primitives.


10.4 PowerMAX Input-Output Controls

IRIX supports the rather typical set of SVR 4.2 data link input-output controls as follows:

DLIOCSMIBSet MIB.
DLIOCGMIBGet MIB.
DLIOCSENADDRSet Ethernet address.
DLIOCGENADDRGet Ethernet address.
DLIOCSLPCFLGSet local packet copy flag.
DLIOCGLPCFLGGet local packet copy flag.
DLIOCSPROMISCToggle promiscuous state.
DLIOCGPROMISCGet promiscuous state.
DLIOCADDMULTIAdd multicast address.
DLIOCDELMULTIDelete multicast address.
DLIOCGETMULTIGet multicast address list.
DLIOCDISABLEDisable controller.
DLIOCENABLEEnable controller.
DLIOCRESETReset controller.
DLIOCCSMACDMODEToggle CSMA-CD mode.

Strangely enough, the DLIOCLLC2MODE and DLIOCRAWMODE input-output controls are not documented.

See dlpi_ioctl(4) for more detail.


10.5 PowerMAX Drivers and Modules


10.6 PowerMAX Libraries


10.7 PowerMAX Utilities


10.8 PowerMAX Management


10.9 PowerMAX Summary


11 Porting from Solaris


11.1 Solaris Driver Addressing


11.1.1 Solaris Driver Naming


11.1.2 Solaris PPA Selection


11.1.3 Solaris SAP Addressing


11.1.4 Solaris Primitive Addresses


11.1.5 Solaris Quality of Service Parameters


11.2 Solaris Driver Features


11.2.1 Solaris LAN Operation

11.2.1.1 Solaris Ethernet and SNAP Operation

11.2.1.2 Solaris LLC Type 1 Operation

11.2.1.3 Solaris LLC Type 2 Operation

11.2.1.4 Solaris LLC Type 3 Operation


11.2.2 Solaris WAN Operation


11.2.3 Solaris Driver Modes

11.2.3.1 Solaris Promiscuous Mode

11.2.3.2 Solaris Raw Mode

11.2.3.3 Solaris LLC2 Mode

LLC2 mode is a mode provided primarily by systems that do not support the DLPI connection-oriented mode. It allows the DLS User to include control octets in the data payload. Otherwise, LLC data would normally be sent by a DL_CLDLS DLS provider as an Unnumbered Information (UI) frame.

11.2.3.4 Solaris CSMA/CD Mode

11.2.3.5 Solaris Fast Path

11.2.3.6 Solaris Combined Mode


11.3 Solaris Primitives

11.3.1 Solaris Supported Primitives

The following primitives are supported by Solaris:

The following connectionless mode primitives are supported by Solaris:

The following connectionless-oriented mode primitives are supported by Solaris:

11.3.2 Solaris Unsupported Primitives

The following primitives are not supported by Solaris:

The following acknowledged connectionless mode primitives are not supported by Solaris:

11.3.3 Solaris Primitive Porting Considerations

DL_PROMISCON_REQ

OpenSS7 supports this primitive being issued multiple times by the DLS users for the same promiscuous level without generating a fatal or non-fatal error. Solaris documentation is silent on the matter.

Care should be taken when porting Solaris drivers, modules and applications to OpenSS7 that the DLS user does not rely upon the DLS provider returning an error should this primitive be issued multiple times for the same promiscuous level.

DL_PROMISCOFF_REQ

OpenSS7 supports this primitive being issued multiple times by the DLS users for the same promiscuous level without generating a fatal or non-fatal error. Solaris documentation is silent on the matter.

Care should be taken when porting Solaris drivers, modules and applications to OpenSS7 that the DLS user does not rely upon the DLS provider returning an error should this primitive be issued multiple times for the same promiscuous level.

11.3.4 Solaris Extension Primitives

Solaris provides the following extension primitives:


11.4 Solaris Input-Output Controls

See dlpi_ioctl(4) for more detail.


11.5 Solaris Drivers and Modules


11.6 Solaris Libraries


11.7 Solaris Utilities


11.8 Solaris Management


11.9 Solaris Summary


12 Porting from Solstice X.25


12.1 Solstice X.25 Driver Addressing


12.1.1 Solstice X.25 Driver Naming


12.1.2 Solstice X.25 PPA Selection


12.1.3 Solstice X.25 SAP Addressing


12.1.4 Solstice X.25 Primitive Addresses


12.1.5 Solstice X.25 Quality of Service Parameters


12.2 Solstice X.25 Driver Features


12.2.1 Solstice X.25 LAN Operation

12.2.1.1 Solstice X.25 Ethernet and SNAP Operation

12.2.1.2 Solstice X.25 LLC Type 1 Operation

12.2.1.3 Solstice X.25 LLC Type 2 Operation

12.2.1.4 Solstice X.25 LLC Type 3 Operation


12.2.2 Solstice X.25 WAN Operation


12.2.3 Solstice X.25 Driver Modes

12.2.3.1 Solstice X.25 Promiscuous Mode

12.2.3.2 Solstice X.25 Raw Mode

12.2.3.3 Solstice X.25 LLC2 Mode

LLC2 mode is a mode provided primarily by systems that do not support the DLPI connection-oriented mode. It allows the DLS User to include control octets in the data payload. Otherwise, LLC data would normally be sent by a DL_CLDLS DLS provider as an Unnumbered Information (UI) frame.

12.2.3.4 Solstice X.25 CSMA/CD Mode

12.2.3.5 Solstice X.25 Fast Path

12.2.3.6 Solstice X.25 Combined Mode


12.3 Solstice X.25 Primitives

12.3.1 Solstice X.25 Supported Primitives

The following primitives are supported by Solstice X.25:

The following connection-oriented mode primitives are supported by Solstice X.25:

12.3.2 Solstice X.25 Unsupported Primitives

The following primitives are not supported by Solstice X.25:

The following connectionless mode primitives are not supported by Solstice X.25:

The following acknowledged connectionless mode primitives are not supported by Solstice X.25:

12.3.3 Solstice X.25 Primitive Porting Considerations

DL_PROMISCON_REQ

Solstice X.25 does not support this primitive. OpenSS7 supports this primitive even for DLS providers that do not support or are not bound in a connectionless mode.

Care should be taken when porting Solstice X.25 DLPI drivers, modules or applications to OpenSS7 that the DLS User does not reply upon the DLS provider returning a non-fatal error in the event that this primitive is issued.

DL_PROMISCOFF_REQ

Solstice X.25 does not support this primitive. OpenSS7 supports this primitive even for DLS providers that do not support or are not bound in a connectionless mode.

Care should be taken when porting Solstice X.25 DLPI drivers, modules or applications to OpenSS7 that the DLS User does not reply upon the DLS provider returning a non-fatal error in the event that this primitive is issued.

12.3.4 Solstice X.25 Extension Primitives

There are no extension primitives for Solstice X.25.


12.4 Solstice X.25 Input-Output Controls

See dlpi_ioctl(4) for more detail.


12.5 Solstice X.25 Drivers and Modules


12.6 Solstice X.25 Libraries


12.7 Solstice X.25 Utilities


12.8 Solstice X.25 Management


12.9 Solstice X.25 Summary


13 Porting from SVR4.2

Here, SVR4.2 refers to “UNIX System V Release 4.2 MP,” and any number of UNIX variants based on SVR 4.2 MP, such as UnixWare 1.0, UnixWare 2.0, UnixWare 2.1, SUPER-UX Release 9.2, UXP/V V10L10, and others.

For UnixWare 7.1.x, see Porting from UnixWare.

Under UnixWare 1 and 2, DLPI was used to implement network adapters. On all version of UnixWare, DLPI is used to implement network protocol stacks.


13.1 SVR4.2 Driver Addressing


13.1.1 SVR4.2 Driver Naming


13.1.2 SVR4.2 PPA Selection


13.1.3 SVR4.2 SAP Addressing


13.1.4 SVR4.2 Primitive Addresses


13.1.5 SVR4.2 Quality of Service Parameters


13.2 SVR4.2 Driver Features


13.2.1 SVR4.2 LAN Operation

13.2.1.1 SVR4.2 Ethernet and SNAP Operation

13.2.1.2 SVR4.2 LLC Type 1 Operation

13.2.1.3 SVR4.2 LLC Type 2 Operation

13.2.1.4 SVR4.2 LLC Type 3 Operation


13.2.2 SVR4.2 WAN Operation


13.2.3 SVR4.2 Driver Modes

13.2.3.1 SVR4.2 Promiscuous Mode

[UnixWare 7] MDI support for promicuous mode differs from earlier driver architectures, where multiple opens were enabled:

DLPI and ODI drivers (UnixWare 1 and 2) can issue the DL_BIND_REQ primitive to the PROMISCUOUS_SAP sap. The following STREAMS input-output controls can then be sent:

13.2.3.2 SVR4.2 Raw Mode

13.2.3.3 SVR4.2 LLC2 Mode

LLC2 mode is a mode provided primarily by systems that do not support the DLPI connection-oriented mode. It allows the DLS User to include control octets in the data payload. Otherwise, LLC data would normally be sent by a DL_CLDLS DLS provider as an Unnumbered Information (UI) frame.

13.2.3.4 SVR4.2 CSMA/CD Mode

13.2.3.5 SVR4.2 Fast Path

13.2.3.6 SVR4.2 Combinded Connectionless and Connection-Oriented Modes


13.3 SVR4.2 Primitives


13.4 SVR4.2 Extension Primitives


13.5 SVR4.2 Input-Output Controls

DLIOCSMIB – Get MIB statistics (DL_mib_t).
DLIOCGMIB – Get MIB statistics (DL_mib_t).
DLIOCSENADDR – Set physical (MAC) address.
DLIOCGENADDR – Return Ethernet (MAC) address.
DLIOCSLPCFLG – Set local copy packet flag (send local packets on wire).
DLIOCGLPCFLG – Get local copy packet flag (send local packets on wire).
DLIOCSPROMISC – Set promiscuous mode flag.
DLIOCGPROMISC – Get promiscuous mode flag.

The DL_PROMISCON_REQ primitive is defined for DLPI 2.0.0 (UnixWare 7 and SCO OpenServer Release 5) and the DLPI 1.x equivalent is the DLIOCSPROMISC input-output control. Note, however, that these primitives are NAK’ed by the DLPI module because promiscuous mode is not implemented through DLPI (On UnixWare 7). The only way to implement promiscuous mode for UnixWare 7 and SCO OpenServer Release 5 is with MDI.

DLIOCADDMULTI – Add multicast address.
DLIOCDELMULTI – Delete multicast address.
DLIOCGETMULTI – Return list of multicast addresses.
DLIOCDISABLE – Disable controller – nearest equivalent is DL_UNBIND_REQ.
DLIOCENABLE – Enable controller – nearest equivalent is DL_BIND_REQ.
DLIOCRESET – Reset controller – nearest equivalent is to close and open the driver.
DLIOCCSMACDMODE – Switch SAP type to RAW.
DLIOCRAWMODE – Toggle RAW mode (Token-Ring adapters).
DLIOCLLC2MODE – Toggle LLC2 mode (Token-Ring adapters).

See dlpi_ioctl(4) for more detail.


13.6 SVR4.2 Drivers and Modules


13.7 SVR4.2 Libraries


13.8 SVR4.2 Utilities


13.9 SVR4.2 Management


13.10 SVR4.2 Summary


14 Porting from UnixWare

This chapter highlights porting DLPI drivers, modules and applications from UnixWare to OpenSS7 and Linux.

For the purpose of the current disussion, UnixWare refers to the “merged product,” that is, the UnixWare 7.x.x releases. For UnixWare 1.0, 1.1, 2.0, 2.1, 2.1.x see the section on porting from SVR4.2, Porting from SVR4.2.


14.1 UnixWare Driver Addressing


14.1.1 UnixWare Driver Naming


14.1.2 UnixWare PPA Selection


14.1.3 UnixWare SAP Addressing


14.1.4 UnixWare Primitive Addresses


14.1.5 UnixWare Quality of Service Parameters


14.2 UnixWare Driver Features


14.2.1 UnixWare LAN Operation

14.2.1.1 UnixWare Ethernet and SNAP Operation

14.2.1.2 UnixWare LLC Type 1 Operation

The UnixWare DLPI driver supports LLC Type 1 and Ethernet operation in the usual manner.

14.2.1.3 UnixWare LLC Type 2 Operation

UnixWare is one of the DLPI implementations that does not directly support LLC Type 2 operation. Also, no LLC2 Mode is apparently provided.

14.2.1.4 UnixWare LLC Type 3 Operation

UnixWare, as the other UNIX derivatives, does not directly support LLC Type 3 operation.


14.2.2 UnixWare WAN Operation


14.2.3 UnixWare Driver Modes

14.2.3.1 UnixWare Promiscuous Mode

Network adapter drivers normally process only those network frames containing the MAC address of the device they control or broadcast addresses. When promiscious mode is enabled, network frames bound for any MAC address are received and passed to the MDI consumer, whether a kernel driver or user program. This can be useful for network troubleshooting; network monitors and other tools rely upon promiscuous mode.

The UnixWare 7 and SCO OpenServer MDI specification provides optional support for promiscuous mode; it is no required. To implement promiscuous mode in an MDI driver, you must code a ‘switch’ statement to process the MDI MACIOC_PROMISC input-output control. For UnixWare 7 MDI drivers, the bcfg(4dsp) file includes the mandatory PROMISCUOUS parameter that must be set to ‘true’ if the driver supports promiscuous mode, or ‘false’ if it does not.

These MDI elements mandate promiscuous mode behaviour:

open(D2mdi)

must disable promiscuous mode if it was set by a previous MAC user that had closed the driver before open(2s) was called. Also, to ensure that open(2s) is not called more than one time before close(2s) is called, the drivers should fail subsequent calls to open(2s).

close(D2mdi)

must disable promiscious mode when the MDI device is closed.

M_IOCTL(D7str)

includes a ‘switch’ statement to process the MACIOC_PROMISC input-output control.

The DL_PROMISCON_REQ primitive is defined for DLPI 2.0.0 (UnixWare 7 and SCO OpenServer Release 5) and the DLPI 1.x equivalent is the DLIOCSPROMISC input-output control Note, however, that these primitives are NAK’ed by the DLPI module because promiscuous mode is not implemented through DLPI. The only way to implement promiscuous mode for UnixWare 7 and SCO OpenServer Release 5 is with MDI.

To access a MDI device in promiscuous mode:

  1. Open the /dev/mdi device.
  2. Send a MAC_BIND_REQ primitive to the device with the putmsg(2s) or putpmsg(2s) system call.
  3. Send a MACIOC_PROMISC input-output control to enable promiscous mode.
  4. Read all frames with getmsg(2s) or getpmsg(2s) until “done”.
  5. Close the file descriptor for