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 OpenGroup¹ 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-STREAMS². 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.³

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:

Additional funding for The OpenSS7 Project was provided by:

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:

Supporters

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

Telecommunications

Aerospace and Military

Financial, Business and Security

Education, Health Care and Nuclear Power

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:

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-STREAMS⁹.

1.1 Overview

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

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

• Linux DLPI Driver (streams-dl.o),
• Linux IP to DLPI Driver (streams-ldl.o),
• DLPI to Linux IP Driver (streams-ip_to_dlpi.o), and
• DLPI to Linux IP Module (streams-ip_strm_mod.o).

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.¹² 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:

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.¹³

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,¹⁴ UnixWare.¹⁵

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,¹⁶ HP-UX,¹⁷ Solstice X.25.¹⁸

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.¹⁹ 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,²⁰ 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,²¹ 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:

• DL_PROMISCON_REQ,
• DL_PROMISCOFF_REQ,
• DL_ENABMULTI_REQ,
• DL_DISABMULTI_REQ, and
• DL_GET_STATISTICS_REQ.

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:

• Places the DLPI Stream into raw mode, where link layer headers are included in both DL_UNITDATA_IND and DL_UNITDATA_REQ primitives.
• Resets statistics associated with a PPA, SAP or Connection.
• A fast-path permitting the DLS user (network layer) to complete the DLSAP address.
• A mechanism for configuring connection-oriented mode protocol parameters for ISO/IEC 8802-2 (IEEE 802.2) LLC Type 2 and ISO/IEC 8208 LAPB.
• A mechanism for collecting connection statistics for ISO/IEC 8802-2 (IEEE 802.2) LLC Type 2 and ISO/IEC 8208 LAPB connections. (For some reason the DL_GET_STATISTICS_REQ and DL_GET_STATISTICS_ACK primitives are considered insufficient. Perhaps it is that these primitives were optionally provided only in later DLPI standard revisions.)
• A mechanism for obtaining the Physical Points of Attachment (PPA) for installed devices.

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:

• DL_ATTACH_REQ, DL_DETACH_REQ

  OpenSS7 implements these primitives in a compatible manner. The form of the Physical Point of Attachment (PPA) for OpenSS7 may differ from that of AIX.

  Care should be taken when porting DLPI drivers, modules and applications from AIX that the DLS user follows the recommendations of the DLPI standard with regard to the handling of PPAs as an oqaque value. The management system or lookup functions from which the DLS user obtains the PPA must be adjusted to deliver appropriate Linux Fast-STREAMS PPAs.

• DL_BIND_REQ, DL_BIND_ACK, DL_UNBIND_REQ

  OpenSS7 implements these primitives in a compatible manner. The form of the Service Access Point (SAP) values for OpenSS7 may differ from that of AIX.

• DL_SUBS_BIND_REQ, DL_SUBS_BIND_ACK, DL_SUBS_UNBIND_REQ

  OpenSS7 implements these primitives in a compatible manner. The form of the Service Access Point (SAP) values for OpenSS7 may differ from that of AIX.

• DL_INFO_REQ, DL_INFO_ACK

  OpenSS7 implements these primitives in a compatible manner.

• DL_PHYS_ADDR_REQ, DL_PHYS_ADDR_ACK

  OpenSS7 implements these primitives in a compatible manner.

• DL_ENABMULTI_REQ, DL_DISABMULTI_REQ

  OpenSS7 implements these primitives in a compatible manner where they are supported by the protocol and underlying device.

• DL_PROMISCON_REQ

  AIX documents that should this primitive be issued multiple times for the same promicuous level, that the duplicate primitives will be acknowledged with the DL_OK_ACK primitive and the effects of the primitive ignored (that is, no non-fatal error will be generated). OpenSS7 also supports this behaviour in support of porting AIX drivers, modules and applications to Linux Fast-STREAMS.

  Nevertheless, care should be taken when porting AIX drivers, modules and applications to OpenSS7 that the DLS user does not rely upon the DLS provider not 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. AIX documentation is silent on the matter.

  Care should be taken when porting AIX 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_GET_STATISTICS_REQ, DL_GET_STATISTICS_ACK

  OpenSS7 implements these primitives in a compatible manner, however, AIX does not document well the format of the returned statistics.

• DL_ERROR_ACK, DL_OK_ACK

  OpenSS7 implements these primitives in a compatible manner.

  Care should be taken that the DLS user does not rely upon any specific dl_unix_errno value.

The following XID and TEST primitives are supported by AIX:

• DL_TEST_CON, DL_TEST_IND, DL_TEST_REQ, DL_TEST_RES

  OpenSS7 implements these primitives in a compatible manner.

• DL_XID_CON, DL_XID_IND, DL_XID_REQ, DL_XID_RES

  OpenSS7 implements these primitives in a compatible manner.

The following connectionless mode primitives are supported by AIX:

• DL_UNITDATA_REQ

  OpenSS7 implements this primitive in a compatible manner.

• DL_UNITDATA_IND

  OpenSS7 implements this primitive in a compatible manner.

• DL_UDERROR_IND

  OpenSS7 implements this primitive in a compatible manner.

  However, whenever the packet contents are available to be returned with the error, OpenSS7 returns the packet in the data portion (M_DATA) of the primitive.

  Care should be taken when porting DLPI drivers, modules and applications, that the DLS user applications must be ready to receive or discard the data portion associated with this primitive.

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

• DL_CONNECT_REQ

  OpenSS7 implements this primitive in a compatible manner.

  However, AIX does not support quality of service parameters, dl_qos_length and dl_qos_offset, associated with this primitive.

  OpenSS7 supports the QOS parameters described in the DLPI standard: when the dl_qos_length and dl_qos_offset field in the primitive are zero (0), the DLS provider will propose the default quality of service range. Otherwise, the dl_qos_length and dl_qos_offset may describe a DL_QOS_CO_RANGE1 QOS parameter structure.

  Care should be taken when porting AIX drivers, modules and applications to Linux that the dl_qos_length field in the primitive is indeed set to zero (0) (as AIX may, contrary to its documentation, ignore the values).

• DL_CONNECT_IND

  OpenSS7 implements this primitive in a compatible manner.

  However, AIX does not associate quality of service parameters, dl_qos_length and dl_qos_offset, with this primitive. Both dl_qos_length and dl_qos_offset are documented as set to zero (0) by AIX.

  OpenSS7 supports the QOS parameters described in the DLPI standard: when the dl_qos_length and dl_qos_offset fields are set to zero (0), no quality of service information was available from the remote station. Otherwise, the dl_qos_length and dl_qos_offset will describe a DL_QOS_CO_RANGE1 QOS parameter structure describing the range of quality of service parameters supported by both the remote and local providers for this data link.

  Care should be taken when porting AIX drivers, modules and applications to Linux that the dl_qos_length field in the primitive is ignored and that the DLS user provides sufficient storage to receive the entire primitive with quality of service parameters intact.

• DL_CONNECT_RES

  OpenSS7 implements this primitive in a compatible manner.

• DL_CONNECT_CON

  OpenSS7 implements this primitive in a compatible manner. However, AIX does not associate quality of service parameters, dl_qos_length and dl_qos_offset, with this primitive. Both dl_qos_length and dl_qos_offset are set to zero (0) by AIX.

• DL_TOKEN_REQ, DL_TOKEN_ACK

  OpenSS7 implements these primitives in a compatible manner. However, AIX does not specify the form of the token. OpenSS7 does not use a small integer token value, dl_token, but rather a unsigned long value derived from the queue pointer associated with the Stream. Care should be taken that the DLS user provides sufficient storage to save the entire token value.

• DL_DATA_REQ, DL_DATA_IND
• DL_DISCONNECT_REQ, DL_DISCONNECT_IND
• DL_RESET_REQ, DL_RESET_IND, DL_RESET_RES, DL_RESET_CON

5.3.2 AIX Unsupported Primitives

The following primitives are not supported by AIX:

• DL_UDQOS_REQ

  AIX does not support this primitive and a non-fatal error with error code [DL_NOTSUPPORTED] will be returned in response to this primitive. OpenSS7 supports this primitive.

  Care should be taken when porting AIX drivers, modules and applications to OpenSS7 that the DLS user does not rely upon the DLS provider returning a non-fatal error should this primitive be issued by the DLS user.

• DL_SET_PHYS_ADDR_REQ

  AIX does not support this primitive and a non-fatal error with error code [DL_NOTSUPPORTED] will be returned in response to this primitive. OpenSS7 supports this primitive for devices that support setting of the physical address.

  Care should be taken when porting AIX drivers, modules and applications to OpenSS7 that the DLS user does not rely upon the DLS provider returning a non-fatal error should this primitive be issued by the DLS user.

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

• DL_DATA_ACK_REQ, DL_DATA_ACK_IND, DL_DATA_ACK_STATUS_IND, DL_REPLY_REQ, DL_REPLY_IND, DL_REPLY_UPDATE_REQ, DL_REPLY_STATUS_IND, DL_REPLY_UPDATE_STATUS_IND

  AIX does not support these primitives and a non-fatal error with error code [DL_NOTSUPPORTED] will be returned in response to these primitives. OpenSS7 does not support these primitives either.

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:

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:

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

6.3.2 AIXlink/X.25 Unsupported Primitives

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

• DL_ATTACH_REQ, DL_DETACH_REQ
• DL_SUBS_BIND_REQ, DL_SUBS_BIND_ACK, DL_SUBS_UNBIND_REQ
• DL_ENABMULTI_REQ, DL_DISABMULTI_REQ
• DL_PROMISCON_REQ, DL_PROMISCOFF_REQ
• DL_PHYS_ADDR_REQ, DL_PHYS_ADDR_ACK, DL_SET_PHYS_ADDR_REQ
• DL_GET_STATISTICS_REQ, DL_GET_STATISTICS_ACK

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

• DL_TEST_REQ, DL_TEST_IND, DL_TEST_RES, DL_TEST_CON, DL_XID_REQ, DL_XID_IND, DL_XID_RES, DL_XID_CON

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

• DL_CONNECT_IND, DL_CONNECT_RES

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

• DL_UNITDATA_REQ, DL_UDQOS_REQ, DL_UNITDATA_IND, DL_UDERROR_IND

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

• DL_DATA_ACK_REQ, DL_DATA_ACK_IND, DL_DATA_ACK_STATUS_IND, DL_REPLY_IND, DL_REPLY_REQ, DL_REPLY_STATUS_IND, DL_REPLY_UPDATE_REQ, DL_REPLY_UPDATE_STATUS_IND

6.3.3 AIXlink/X.25 Primitive Porting Considerations

• DL_ATTACH_REQ

  AIXlink/X.25 does not support this primitive. Supporting this primitive and the corresponding Style 2 DLS provider is optional. OpenSS7 does not support this primitive for Style 1 DLS providers either.

• DL_DETACH_REQ

  AIXlink/X.25 does not support this primitive. Supporting this primitive and the corresponding Style 2 DLS provider is optional. OpenSS7 does not support this primitive for Style 1 DLS providers either.

• DL_DISABMULTI_REQ

  AIXlink/X.25 does not support this primitive. Supporting this primitive is optional for the DLS provider. OpenSS7 does not support this primitive for LAPB either.

• DL_ENABMULTI_REQ

  AIXlink/X.25 does not support this primitive. Supporting this primitive is optional for the DLS provider. OpenSS7 does not support this primitive for LAPB either.

• DL_GET_PHYS_ADDR_REQ

  AIXlink/X.25 does not support this primitive. Supporting this primitive is optional for the DLS provider. OpenSS7 does not support this primitive for LAPB either.

• DL_GET_PHYS_ADDR_ACK

  AIXlink/X.25 does not support this primitive. Supporting this primitive is optional for the DLS provider. OpenSS7 does not support this primitive for LAPB either.

• DL_SET_PHYS_ADDR_REQ

  AIXlink/X.25 does not support this primitive. Supporting this primitive is optional for the DLS provider. OpenSS7 does not support this primitive for LAPB either.

• DL_GET_STATISTICS_REQ

  AIXlink/X.25 does not support this primitive. Supporting this primitive is optional for the DLS provider. OpenSS7 supports this primitive.

• DL_GET_STATISTICS_ACK

  AIXlink/X.25 does not support this primitive. Supporting this primitive is optional for the DLS provider. OpenSS7 supports this primitive.

• DL_PROMISCOFF_REQ

  AIXlink/X.25 does not support this primitive. Supporting this primitive is optional for the DLS provider. OpenSS7 supports this primitive.

• DL_PROMISCON_REQ

  AIXlink/X.25 does not support this primitive. Supporting this primitive is optional for the DLS provider. OpenSS7 supports this primitive.

• DL_SUBS_BIND_ACK

  AIXlink/X.25 does not support this primitive. Supporting this primitive is optional for the DLS provider. OpenSS7 does not support this primitive for X.25 LAPB.

• DL_SUBS_BIND_REQ

  AIXlink/X.25 does not support this primitive. Supporting this primitive is optional for the DLS provider. OpenSS7 does not support this primitive for X.25 LAPB.

• DL_SUBS_UNBIND_REQ

  AIXlink/X.25 does not support this primitive. Supporting this primitive is optional for the DLS provider. OpenSS7 does not support this primitive for X.25 LAPB.

• DL_CONNECT_IND

  AIXlink/X.25 does not support this primitive. OpenSS7 supports this primitive.

  Care should be taken when porting AIX drivers, modules and applications to OpenSS7 that the DLS user never binds with a non-zero dl_max_conind value so that the DLS provider does not issue this primitive.

• DL_CONNECT_RES

  AIXlink/X.25 does not support this primitive. OpenSS7 supports this primitive.

  Care should be taken when porting AIX drivers, modules and applications to OpenSS7 that the DLS user never binds with a non-zero dl_max_conind value so that the DLS provider will not accept this primitive.

• DL_PROMISCON_REQ

  AIXlink/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 AIXlink/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

  AIXlink/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 AIXlink/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.

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:

• Normally raw modes are initiated using implementation-defined input-output controls. HP-UX uses an implementation-defined service mode instead.
• Normally raw data messages are delivered to and accepted from the DLS User using existing DLPI primitives. HP-UX uses the implementation-defined DL_HP_RAWDATA_REQ and DL_HP_RAWDATA_IND primitives instead.

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:

• DL_SET_PHYS_ADDR_REQ

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

• DL_DATA_ACK_REQ, DL_DATA_ACK_IND, DL_DATA_ACK_STATUS_IND, DL_REPLY_IND, DL_REPLY_REQ, DL_REPLY_STATUS_IND, DL_REPLY_UPDATE_REQ, DL_REPLY_UPDATE_STATUS_IND

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:

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

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:²²

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:

The following connectionless mode primitives are supported by IRIX:

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

8.3.2 IRIX Unsupported Primitives

The following primitives are not supported by IRIX:

• DL_PROMISCON_REQ

  Not supported by IRIX, although I trust that it will respsond to the DLIOCSPROMISC input-output control, regardless of it not being documented.

• DL_PROMISCOFF_REQ

  Not supported by IRIX, although I trust that it will respsond to the DLIOCSPROMISC input-output control, regardless of it not being documented.

• DL_GET_STATISTICS_REQ, DL_GET_STATISTICS_ACK

  Not supported by IRIX, although I trust that it will respsond to the DLIOCGMIB input-output control, regardless of it not being documented.

The following connectionless mode primitives are not supported by IRIX:

• DL_UDQOS_REQ

  IRIX does not support quality of service parameters for connectionless mode of operation and this primitive is therefore unnecessary and not supported.

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

• DL_DATA_ACK_REQ, DL_DATA_ACK_IND, DL_DATA_ACK_STATUS_IND, DL_REPLY_IND, DL_REPLY_REQ, DL_REPLY_STATUS_IND, DL_REPLY_UPDATE_REQ, DL_REPLY_UPDATE_STATUS_IND

  IRIX, like most other UNIX implementations, does not support acknowledged connectionless mode data link service. Therefore, none of these primitives are applicable. Note that ISO/IEC 8802-2 (IEEE 802.2) does not require that either LLC Type 2 or LLC Type 3 be supported.

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:

• DL_ATTACH_REQ – Requests that the DLS provider associate a physical point of attachment (PPA) with a Stream. Used on style 2 providers only.
• DL_DETACH_REQ – Request the DLS provider disassociated a physical point of attachment(PPA) with a Stream.
• DL_BIND_REQ – Requests that the DLS provider bind a DLSAP to the Stream. The DLS user must identify the address of the DLSAP to be bound ot the Stream.
• DL_BIND_ACK – Reports the successful bind of a DLSAP to a Stream, and returns the bound DLSAP address to the DLS user. Generated in response to a DL_BIND_REQ.
• DL_UNBIND_REQ – Requests that the DLS provider unbind the DLSAP that was bound by a previous DL_BIND_REQ from this Stream.
• DL_SUBS_BIND_REQ – Request the DLS provider bind a subsequent DLSAP to a Stream. There are two classes of subsequent bind requests: DL_HIERARCHICAL_BIND and DL_PEER_BIND. DL_HIERARCHICAL_BIND requests are only valid for SNAPs (see the IEEE 802.1 specification) and you must have bound to the SNAP sap (0xAA) with a DL_BIND_REQ before issuing the DL_SUBS_BIND_REQ for the SNAP. DL_PEER_BIND requests binds to additional saps but does not change the DLSAP address of the Stream.
• DL_SUBS_BIND_ACK – The positive response to a DL_SUBS_BIND_REQ from the DLS provider.
• DL_SUBS_UNBIND_REQ – Requests the DLS provider to unbind a SAP that was previously bound with a DL_SUBS_BIND_REQ.
• DL_INFO_REQ – Requests the DLS provider return information about the DLPI Stream.
• DL_INFO_ACK – Response to DL_INFO_REQ primitive; conveys information about the DLPI Stream.
• DL_OK_ACK – Acknowledges to the DLS user that a previously issued request or response primitive was successfully received.
• DL_ERROR_ACK – Informs the DLS user of a previously issued request or response that was invalid.
• DL_ENABMULTI_REQ – Requests the DLS provider enable a specific multicast address. (The OSF implementation requires that the state is DS_IDLE.
• DL_DISABMULTI_REQ – Requests the DLS provider disable a specific multicast address.
• DL_PHYS_ADDR_REQ – Requests that the DLS provider return either the default (factory) or current value of the physical address associated with the Stream, depending upon the value of the address type selected in the request.
• DL_PHYS_ADDR_ACK – Returns the value for the physical address to the DLS user in response to a DL_PHYS_ADDR_REQ.
• DL_TEST_REQ – Requests the DLS provider to transmit a TEST command DLSDU on behalf of the DLS user.
• DL_TEST_IND – Conveys to the DLS user that a DLSDU TEST command DLSDU was received.
• DL_TEST_RES – Requests the DLS provider to transmit a TEST response on behalf of the DLS user.
• DL_TEST_CON – Conveys that a DLSDU TEST response was received in response to a DL_TEST_REQ.
• DL_XID_REQ – Requests the DLS provider to send an XID command DLSUD on behalf of the DLS user.
• DL_XID_IND – Conveys to the DLS user that an XID command DLSDU was received.
• DL_XID_RES – Requests the DLS provider to send an XID response DLSDU on behalf of the DLS user.
• DL_XID_CON – Conveys that a XID DLSDU was received in response to a DL_XID_REQ.

The following connectionless mode primitives are supported by OSF:

• DL_UNITDATA_REQ – Conveys one DLSDU from the DLS user to the DLS provider for transmission to a peer DLS user.
• DL_UNITDATA_IND – Conveys one DLSDU from the DLS provider to the DLS user.
• DL_UDERROR_IND – Informs the DLS user that a previously sent DL_UNITDATA_REQ failed.

9.3.2 OSF Unsupported Primitives

The following primitives are not supported by OSF:

• DL_PROMISCON_REQ, DL_PROMISCOFF_REQ

  OSF does not support promiscuous mode on the DLPI driver. For promiscuous mode, use the DLI sockets interface.

• DL_GET_STATISTICS_REQ, DL_GET_STATISTICS_ACK

  OSF does not support statistics collection on the DLPI driver. For statistics collection, the MIBs or the BSD functions are used.

• DL_SET_PHYS_ADDR_REQ

  OSF does not support setting the physical address on the interface using the DLPI driver. This is possibly affected using ifconfig(8) or some such BSD utility.

The following connectionless mode primitives are not supported by OSF:

• DL_UDQOS_REQ

  OSF does not support quality of service parameters.

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

• 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

  OSF does not support connection-oriented data link service on the DLPI driver and so all connection-oriented data link service mode primitives are not supported. It is not required to support LLC Type 2 operation on a LAN station.

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

• DL_DATA_ACK_IND, DL_DATA_ACK_REQ, DL_DATA_ACK_STATUS_IND, DL_REPLY_REQ, DL_REPLY_IND, DL_REPLY_STATUS_IND, DL_REPLY_UPDATE_REQ, DL_REPLY_UPDATE_STATUS_IND

  OSF does not support acknowledged connectionless data link service on the DLPI driver and so these primitives are not supported. It is not required to support acknowledged connectionless data link service LLC Type 3 on a LAN station.

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.

• ND_GET – Used to obtain the string representation of any number of kernel identifiers. In this case, “dl_ifnames” is used to identify the available PPAs on the system.

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:

• DL_INFO_REQ
• DL_INFO_ACK
• DL_OK_ACK
• DL_ERROR_ACK
• DL_BIND_ACK
• DL_BIND_REQ
• DL_SUBS_BIND_ACK
• DL_SUBS_BIND_REQ
• DL_SUBS_UNBIND_REQ
• DL_UNBIND_REQ
• DL_TEST_REQ
• DL_TEST_CON

The following connectionless mode primitives are supported by PowerMAX:

• DL_UNITDATA_REQ
• DL_UNITDATA_IND
• DL_UDERROR_IND

10.3.2 PowerMAX Unsupported Primitives

The following primitives are not supported by PowerMAX:

• DL_ATTACH_REQ, DL_DETACH_REQ

  Needed only for Style 2 and PowerMAX is only Style 1 drivers.

• DL_ENABMULTI_REQ, DL_DISABMULTI_REQ

  Some of the functionality of these primitives can be achieved with the DLIOCADDMULTI and DLIOCDELMULTI input-output controls.

• DL_PROMISCON_REQ, DL_PROMISCOFF_REQ

  Some of the functionality of this primitive can be acheived with the DLIOCSPROMISC and DLIOCGPROMISC input-output controls.

• DL_XID_REQ, DL_XID_IND, DL_XID_RES, DL_XID_CON

  PowerMAX does not appear to support XID (in interaction with the DLS User) at all. This does not mean that automatic XID is not supported.

• DL_TEST_IND, DL_TEST_RES

  PowerMAX does not appear to support TEST indications and reponses (in interaction with the DLS user) at all. This does not mean that automatic TEST is not supported.

• DL_PHYS_ADDR_REQ, DL_PHYS_ADDR_ACK

  Some of the functionality of this primitive can be acheived with the DLIOCGENADDR input-output control.

• DL_SET_PHYS_ADDR_REQ

  Some of the functionality of this primitive can be acheived with the DLIOCSENADDR input-output control.

• DL_GET_STATISTICS_REQ, DL_GET_STATISTICS_ACK

  Some of the functionality of this primitive can be acheived with the DLIOCGMIB and DLIOCSMIB input-output controls.

The following connectionless mode primitives are not supported by PowerMAX:

• DL_UDQOS_REQ

  PowerMAX does not support quality of service parameters.

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

• 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

  These are connection-oriented mode primitives and PowerMAX only supports some connectionless mode primitives.

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

• DL_DATA_ACK_REQ, DL_DATA_ACK_IND, DL_DATA_ACK_STATUS_IND, DL_REPLY_REQ, DL_REPLY_IND, DL_REPLY_UPDATE_REQ, DL_REPLY_STATUS_IND, DL_REPLY_UPDATE_STATUS_IND

  PowerMAX does not support acknowledged connectionless data link service on the DLPI driver and so these primitives are not supported. It is not required to support acknowledged connectionless data link service LLC Type 3 on a LAN station.

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:

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:

• DL_SET_PHYS_ADDR_REQ

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

• DL_DATA_ACK_REQ, DL_DATA_ACK_IND, DL_DATA_ACK_STATUS_IND, DL_REPLY_IND, DL_REPLY_REQ, DL_REPLY_STATUS_IND, DL_REPLY_UPDATE_REQ, DL_REPLY_UPDATE_STATUS_IND

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:

• DL_AGGR_REQ

  Requests that a DLS provider Stream be added to an aggregate.

• DL_AGGR_IND

  Indicates that a DLS provider Stream has been added to an aggregate.

• DL_UNAGGR_REQ

  Requests that a DLS provider Stream be removed from an aggregate.

• DL_PASSIVE_REQ

  Requests that access be provided to an individual DLS provider Stream regardless of it being a part of an aggregate.

• DL_CAPABILITY_REQ
• DL_CAPABILITY_ACK
• DL_CONTROL_REQ
• DL_CONTROL_ACK
• DL_INTR_MODE_REQ
• DL_NOTIFY_REQ
• DL_NOTIFY_ACK
• DL_NOTIFY_IND

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:

• DL_SUBS_BIND_REQ, DL_SUBS_BIND_ACK, DL_SUBS_UNBIND_REQ
• DL_PROMISCON_REQ, DL_PROMISCOFF_REQ
• DL_SET_PHYS_ADDR_REQ

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

• DL_UNITDATA_REQ, DL_UDQOS_REQ, DL_UNITDATA_IND, DL_UDERROR_IND

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

• DL_DATA_ACK_REQ, DL_DATA_ACK_IND, DL_DATA_ACK_STATUS_IND, DL_REPLY_IND, DL_REPLY_REQ, DL_REPLY_STATUS_IND, DL_REPLY_UPDATE_REQ, DL_REPLY_UPDATE_STATUS_IND

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:

• DLIOCGPROMISC – Determine state of promiscuous mode (on/off).
• DLIOCSPROMISC – Toggle state of promiscuous mode (on/off).²³

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 the /dev/mdi device.

Promiscuous mode must be disabled when MDI drivers are opened (they are usually opened eby the DLPI module), and the DLPI module will not pass the MACIOC_PROMISC input-output control to the driver, because the underlying DL_PROMISCON_REQ primitive is NAK’ed on /dev/netX devices. Because MDI drivers support only one open per device, it is not possible to open the network adapter for both a protocol stack and a network monitoring application at the same time. It is therefore necessary to device an entire network adapter to running network monitors in promiscuous mode, or to use the network adapter card in single-user mode before dlpid has started.

14.2.3.2 UnixWare Raw Mode

UnixWare does not document an Raw mode feature, regardless of it being supported on older versions using the DLIOCRAWMODE input-output control.

14.2.3.3 UnixWare LLC2 Mode

UnixWare does not document an LLC2 mode feature, regardless of it being supported on older versions using the DLIOCLLC2MODE input-output control.

14.2.3.4 UnixWare CSMA/CD Mode

UnixWare does not document a CSMA/CD mode feature, regardless of it being supported on older versions using the DLIOCCSMACDMODE input-output control.

14.2.3.5 UnixWare Fast Path

UnixWare does not document a Fast Path feature.

14.2.3.6 UnixWare Combinded Connectionless and Connection-Oriented Modes

14.3 UnixWare Primitives

14.3.1 UnixWare Supported Primitives

The following local management primitives are supported by UnixWare:

The following XID and TEST primitives are supported by UnixWare:

The following connectionless mode primitives are supported by UnixWare:

14.3.2 UnixWare Unsupported Primitives

The following local management primitives are not supoprted by UnixWare:

• DL_ATTACH_REQ, DL_DETACH_REQ

  These two primitives are not necessary as UnixWare only provides a Style 1 driver.

• DL_PROMISCON_REQ, DL_PROMISCOFF_REQ

  These to primitives are not supported directly and will result in an error of [DL_NOTSUPPORTED]. The input-output control DLIOCSPROMISC is also not supported. Also, the DLPI driver will not pass a MACIOC_PROMISC to the MDI level. It is necessary, according to UnixWare documentation that if promiscuous mode is required at the physical level, DL_PROMISC_PHYS, that a privielged user must open an otherwise unused MDI device Stream and use the MACIOC_PROMISC input-output control on it directly.

The following connectionless mode primitives are not supported by UnixWare:

• DL_UDQOS_REQ

  UnixWare does not support quality of service parameters and so this prmitive is unnecessary.

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

• 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

  UnixWare does not support connection-oriented data link service on the DLPI driver and so all connection-oriented data link service mode primitives are not supported. It is not required to support LLC Type 2 operation on a LAN station.

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

• DL_DATA_ACK_REQ, DL_DATA_ACK_IND, DL_DATA_ACK_STATUS_IND, DL_REPLY_REQ, DL_REPLY_IND, DL_REPLY_STATUS_IND, DL_REPLY_UPDATE_REQ, DL_REPLY_UPDATE_STATUS_IND

  UnixWare does not support acknowledged connectionless data link service on the DLPI driver and so these primitives are not supported. It is not required to support acknowledged connectionless data link service LLC Type 3 on a LAN station.

14.4 UnixWare Extension Primitives

UnixWare defines a number of extension primitives. These extension primitives are documented in the UnixWare Intro(D7dlpi) manual page.

OpenSS7 recognizes all of these primitives and supports those primitives that are applicable to Linux. There is no public record of the numeric values that are assigned to these primitives, so only source compatibility is attempted.²⁴ See the individual manual pages for these primitives in the OpenSS7 package for more information on compability.

Following are the UnixWare extension primitives:

• DL_CLEAR_SR_REQ – clear the source routing table

  OpenSS7 recognizes and supports this primitive as described in Intro(D7dlpi). This primitive is only applicable to Token-Ring DLS Providers.

• DL_CLR_STATISTICS_REQ – clear statistics

  OpenSS7 recognizes and supports this primitive as described in Intro(D7dlpi).

• DL_DISABALLMULTI_REQ – disable all multicast addresses

  OpenSS7 recognizes and supports this primitive as described in Intro(D7dlpi) for MAC and LLC DLS providers.

• DL_DLPI_BILOOPMODE – special primitive for frame testing

  OpenSS7 recognizes but does not support this primitive as its description in Intro(D7dlpi) is lacking.

• DL_ENABALLMULTI_REQ – enable all multicast addresses

  OpenSS7 recognizes and supports this primitive as described in Intro(D7dlpi) for MAC and LLC DLS providers.

• DL_ISDN_MSG – send ISDN data plane message

  OpenSS7 recognizes and supports this primitive as described in Intro(D7dlpi) for LAPD DLS providers. This primitive is not applicable to LAPB, MAC, LLC1 or LLC2 DLS providers.

• DL_MCTABLE_REQ – request a list of multicast MAC addresses

  OpenSS7 recognizes and supports this primitive as described in Intro(D7dlpi) for MAC and LLC DLS providers.

• DL_MCTABLE_ACK – respond with a list of multicast MAC addresses

  OpenSS7 recognizes and supports this primitive as described in Intro(D7dlpi) for MAC and LLC DLS providers.

• DL_SAP_STATISTICS_REQ – request SAP statistics

  OpenSS7 recognizes and supports this primitive as described in Intro(D7dlpi) for MAC and LLC DLS providers.

• DL_SAP_STATISTICS_ACK – respone with SAP statistics

  OpenSS7 recognizes and supports this primitive as described in Intro(D7dlpi) for MAC and LLC DLS providers.

• DL_SET_SRMODE_REQ – set source routing mode

  OpenSS7 recognizes and supports this primitive as described in Intro(D7dlpi). This primitive is only applicable to Token-Ring DLS Providers.

• DL_SET_SRPARMS_REQ – set source routing parameters

  OpenSS7 recognizes and supports this primitive as described in Intro(D7dlpi). This primitive is only applicable to Token-Ring DLS Providers.

• DL_SRTABLE_REQ – request the source routing table

  OpenSS7 recognizes and supports this primitive as described in Intro(D7dlpi). This primitive is only applicable to Token-Ring DLS Providers.

• DL_SRTABLE_ACK – response with the source routing table

  OpenSS7 recognizes and supports this primitive as described in Intro(D7dlpi). This primitive is only applicable to Token-Ring DLS Providers.

14.5 UnixWare Input-Output Controls

The DLPI driver intercepts and response to the following MACIOC input-output contorl commands:

The DLPI driver passes all other MACIOC input-output control commands to the MDI driver beneath it. Other MACIOC input-output control commands are as follows:

See dlpi_ioctl(4) for more detail.

14.6 UnixWare Drivers and Modules

14.7 UnixWare Libraries

14.8 UnixWare Utilities

14.9 UnixWare Management

14.10 UnixWare Summary

15 Developing on OpenSS7

15.1 OpenSS7 Primitives

15.2 OpenSS7 Driver Addressing

15.2.1 OpenSS7 Driver Naming

15.2.2 OpenSS7 PPA Selection

15.2.3 OpenSS7 SAP Addressing

15.2.4 OpenSS7 Primitive Addresses

15.2.5 OpenSS7 Quality of Service Parameters

15.3 OpenSS7 Driver Features

15.3.1 OpenSS7 LAN Operation

15.3.1.1 OpenSS7 Ethernet and SNAP Operation

15.3.1.2 OpenSS7 LLC Type 1 Operation

15.3.1.3 OpenSS7 LLC Type 2 Operation

15.3.1.4 OpenSS7 LLC Type 3 Operation

15.3.2 OpenSS7 WAN Operation

15.3.3 OpenSS7 Driver Modes

15.3.3.1 OpenSS7 Promiscuous Mode

15.3.3.2 OpenSS7 Raw Mode

OpenSS7 supports all of the other forms of Raw Mode identified in this document, and particularly the AIX input-output control, Solaris input-output control, HP-UX data link service, SVR4.2 input-output control, and UnixWare input-output control approaches.

When developing new drivers that must present a raw mode to user-space DLPI applications, the SVR4.2 approach is recommended for OpenSS7. When developing new STREAMS drivers or modules that act as DLS Users, the DLS User can rely upon the fact that the first M_DATA message block.

15.3.3.3 OpenSS7 LLC2 Mode

15.3.3.4 OpenSS7 CSMA/CD Mode

15.3.3.5 OpenSS7 Fast Path

15.3.3.6 OpenSS7 Combined Mode

15.4 OpenSS7 Input-Output Controls

See dlpi_ioctl(4) for more detail.

15.5 OpenSS7 Drivers and Modules

15.6 OpenSS7 Libraries

15.7 OpenSS7 Utilities

15.8 OpenSS7 Management

15.9 OpenSS7 Summary

Licenses

GNU Affero General Public License

Copyright © 2007 Free Software Foundation, Inc. http://fsf.org/

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Preamble

The GNU Affero General Public License is a free, copyleft license for software and other kinds of works, specifically designed to ensure cooperation with the community in the case of network server software.

The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, our General Public Licenses are intended to guarantee your freedom to share and change all versions of a program–to make sure it remains free software for all its users.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.

Developers that use our General Public Licenses protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License which gives you legal permission to copy, distribute and/or modify the software.

A secondary benefit of defending all users’ freedom is that improvements made in alternate versions of the program, if they receive widespread use, become available for other developers to incorporate. Many developers of free software are heartened and encouraged by the resulting cooperation. However, in the case of software used on network servers, this result may fail to come about. The GNU General Public License permits making a modified version and letting the public access it on a server without ever releasing its source code to the public.

The GNU Affero General Public License is designed specifically to ensure that, in such cases, the modified source code becomes available to the community. It requires the operator of a network server to provide the source code of the modified version running there to the users of that server. Therefore, public use of a modified version, on a publicly accessible server, gives the public access to the source code of the modified version.

An older license, called the Affero General Public License and published by Affero, was designed to accomplish similar goals. This is a different license, not a version of the Affero GPL, but Affero has released a new version of the Affero GPL which permits relicensing under this license.

The precise terms and conditions for copying, distribution and modification follow.

1. Definitions.

   “This License” refers to version 3 of the GNU Affero General Public License.

   “Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.

   “The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.

   To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.

   A “covered work” means either the unmodified Program or a work based on the Program.

   To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.

   To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.

   An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.

2. Source Code.

   The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.

   A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.

   The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.

   The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work’s System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.

   The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.

   The Corresponding Source for a work in source code form is that same work.

3. Basic Permissions.

   All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.

   You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.

   Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.

4. Protecting Users’ Legal Rights From Anti-Circumvention Law.

   No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.

   When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work’s users, your or third parties’ legal rights to forbid circumvention of technological measures.

5. Conveying Verbatim Copies.

   You may convey verbatim copies of the Program’s source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.

   You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.

6. Conveying Modified Source Versions.

   You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:

   1. The work must carry prominent notices stating that you modified it, and giving a relevant date.
   2. The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to “keep intact all notices”.
   3. You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
   4. If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.

   A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation’s users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.

7. Conveying Non-Source Forms.

   You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:

   1. Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
   2. Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
   3. Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
   4. Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.
   5. Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.

   A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.

   A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.

   “Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.

   If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).

   The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.

   Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.

8. Additional Terms.

   “Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.

   When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.

   Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:

   1. Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
   2. Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
   3. Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
   4. Limiting the use for publicity purposes of names of licensors or authors of the material; or
   5. Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
   6. Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.

   All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.

   If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.

   Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.

9. Termination.

   You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).

   However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

   Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

   Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.

10. Acceptance Not Required for Having Copies.

    You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.

11. Automatic Licensing of Downstream Recipients.

    Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.

    An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party’s predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.

    You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.

12. Patents.

    A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor’s “contributor version”.

    A contributor’s “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.

    Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor’s essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.

    In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.

    If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient’s use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.

    If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.

    A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.

    Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.

13. No Surrender of Others’ Freedom.

    If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.

14. Remote Network Interaction; Use with the GNU General Public License.

    Notwithstanding any other provision of this License, if you modify the Program, your modified version must prominently offer all users interacting with it remotely through a network (if your version supports such interaction) an opportunity to receive the Corresponding Source of your version by providing access to the Corresponding Source from a network server at no charge, through some standard or customary means of facilitating copying of software. This Corresponding Source shall include the Corresponding Source for any work covered by version 3 of the GNU General Public License that is incorporated pursuant to the following paragraph.

    Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the work with which it is combined will remain governed by version 3 of the GNU General Public License.

15. Revised Versions of this License.

    The Free Software Foundation may publish revised and/or new versions of the GNU Affero General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU Affero General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU Affero General Public License, you may choose any version ever published by the Free Software Foundation.

    If the Program specifies that a proxy can decide which future versions of the GNU Affero General Public License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Program.

    Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.

16. Disclaimer of Warranty.

    THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

17. Limitation of Liability.

    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

18. Interpretation of Sections 15 and 16.

    If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.

one line to give the program's name and a brief idea of what it does.
Copyright (C) year name of author

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see http://www.gnu.org/licenses/.

Also add information on how to contact you by electronic and paper mail.

If your software can interact with users remotely through a network, you should also make sure that it provides a way for users to get its source. For example, if your program is a web application, its interface could display a “Source” link that leads users to an archive of the code. There are many ways you could offer source, and different solutions will be better for different programs; see section 13 for the specific requirements.

You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer” for the program, if necessary. For more information on this, and how to apply and follow the GNU AGPL, see http://www.gnu.org/licenses/.

GNU Free Documentation License

Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
http://fsf.org/

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

1. PREAMBLE

   The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

   This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

   We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

2. APPLICABILITY AND DEFINITIONS

   This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

   A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

   A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

   The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

   The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

   A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

   Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

   The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

   The “publisher” means any person or entity that distributes copies of the Document to the public.

   A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

   The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

3. VERBATIM COPYING

   You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

   You may also lend copies, under the same conditions stated above, and you may publicly display copies.

4. COPYING IN QUANTITY

   If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

   If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

   If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

   It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

5. MODIFICATIONS

   You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

   1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
   2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
   3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
   4. Preserve all the copyright notices of the Document.
   5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
   6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
   7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
   8. Include an unaltered copy of this License.
   9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
   10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
   11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
   12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
   13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
   14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
   15. Preserve any Warranty Disclaimers.

   If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

   You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

   You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

   The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

6. COMBINING DOCUMENTS

   You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

   The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

   In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

7. COLLECTIONS OF DOCUMENTS

   You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

   You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

8. AGGREGATION WITH INDEPENDENT WORKS

   A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

   If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

9. TRANSLATION

   Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

   If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.

    However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

    Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

    Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.

11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

12. RELICENSING

    “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.

    “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.

    “Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.

    An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.

    The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:

    with the Invariant Sections being list their titles, with
    the Front-Cover Texts being list, and with the Back-Cover Texts
    being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

UNIX International DLPI License

This license is from the Revision 2.0.0 Data Link Provider Interface (DLPI) specification published by UNIX International Inc, August 20, 1991:

Copyright © 1991 UNIX International, Inc.
All Rights Reserved.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission to use, copy, modify, and distribute this documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name UNIX International not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. UNIX International makes no representations about the suitability of this documentation for any purpose. It is provided “as is” without express or implied warranty.

UNIX INTERNATIONAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS DOCUMENTATION, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL UNIX INTERNATIONAL BE LIABLE FOR ANY SPECIAL, INDIRECT 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 THE USE OR PERFORMANCE OF THIS DOCUMENTATION.

Notice:

This document is based on the UNIX System Laboratories Data Link Provider Interface (DLPI) specification which was used with permission by the UNIX International OSI Work Group (UI OSIWG). Participation in the UI OSIWG is open to UNIX International members and other interested parties. For further information contact UNIX International at the addresses above.

UNIX International is making this documentation available as a reference point for the industry. While UNIX International believes that these interfaces are well defined in this release of the document, minor changes may be made prior to products conforming to the interfaces being made available from UNIX System Laboratories or UNIX International members.

Trademarks:

UNIX® is a registered trademark of UNIX System Laboratories in the United States and other countries.

X/Open(TM) is a trademark of the X/Open Company Ltd. in the UK and other countries.

Index