odi(7)

Synopsis

#include <sys/lsl.h> 
#include <sys/cmsm.h> 
#include <sys/msmstruc.h> 
#include <sys/tsmdef.h> 
#include <sys/ethdef.h> 
#include <sys/tokdef.h> 
#include <sys/odi.h> 
#include <sys/odi_nsi.h> 
#include <sys/odi_portable.h> 
fd = open ("/dev/$HSM_0", O_RDWR) 

Description

We recommend that you use MAC Driver Interface (MDI) drivers instead. ODI drivers previously supplied with SCO systems have been replaced with MDI drivers. Consult your network adapter vendor concerning availability of MDI drivers for your device. See also the SCO Compatible Hardware Web Pages for complete information about network hardware support on SCO platforms.

The components of the ODI support architecture are described in the following paragraphs.

DLPI/LSL

The DLPI/LSL Dynamic Loadable Module (DLM) is supplied with UnixWare. Conceptually, the DLPI/LSL is a merger of the earlier UnixWare Data Link Provider Interface (DLPI) STREAMS module with the NetWare Link Support Layer (LSL) NetWare Loadable Module. The DLPI/LSL provides the services mandated by the DLPI2 interface specification to STREAMS modules, such as IPX and IP higher up in network protocol stacks. Therefore, no changes in the protocol stacks are required to work with the UnixWare ODI subsystem. For ODI compatibility, the DLPI/LSL presents the interface required by the ODI specification to the MSM layer below it. Internally, the DLPI/LSL performs the essential translation between DLPI semantics and ODI semantics. In particular, the DLPI/LSL binds a UNIX clone device minor number to a Link Service Access Point (LSAP) protocol address and its associated ODI frame type.

MSM

The Media Support Module provides service functions to the TSM and HSM layers below. These services include base kernel services, such as memory management and hardware registration. The MSM also provides the primary service binding of a NIC instance with the DLPI/LSL. The MSM is supplied with UnixWare.

TSM

There is one Topology Support Module for each network topology. UnixWare 2.0 includes TSMs for Ethernet and Token Ring. The HSMs for a given topology use the topology-specific services of the corresponding TSM. In addition, token ring source routing feature is provided by the ODI Source Routing Module (ODISR).

HSM

Each NIC comes with an ODI Hardware Support Module, which performs various services for the NIC. The most important of these services are sending and receiving of frames by the NIC. For a frame type supported by the NIC to be available through ODI, the HSM must also support that frame type.

For Ethernet, UnixWare supports MAC types DL_ETHER and DL_CSMACD, provider style DL_STYLE1, and frame types ETHERNET_802.2, ETHERNET_802.3, ETHERNET_II, and ETHERNET_SNAP.

For Token ring, UnixWare supports MAC type DL_TPR plus LLC2 MODE and RAW MODE pass-through interfaces, provider style DL_STYLE1, and frame types TOKEN-RING and TOKEN-RING_SNAP.

The odi driver can operate as either a cloned or non-cloned device.

A process must issue a DL_BIND_REQ primitive to receive frames from the network. The process must specify the dl_sap member of the dl_bind_req_t structure. The type field of an incoming frame is compared to the dl_sap value. If the values are equal, the frame is placed on the STREAMS read queue of the process. A privileged process may set the dl_sap field to PROMISCUOUS_SAP. PROMISCUOUS_SAP matches all incoming frames.

A privileged process can also bind to a SAP already bound by another process. In cases where a frame qualifies to be sent to more than one process, independent copies of the frame will be made and placed on the STREAMS read queue of each process.

Received frames are delivered in dl_unitdata_ind_t structures. The source and destination address each contain a 6-byte Ethernet address, followed by a 2-byte type value.

Usage

ioctl calls

DLIOCGMIB

Returns the DL_mib_t structure, which contains the Management Information Base (MIB). The MIB holds the Ethernet statistics kept in the driver.

/* 
 * Ether statistics structure. 
 */ 
typedef struct { 
	ulong_t	etherAlignErrors;	/* Frame alignment errors */ 
	ulong_t	etherCRCerrors;		/* CRC erros */ 
	ulong_t	etherMissedPkts;	/* Packet overflow or missed inter */ 
	ulong_t	etherOverrunErrors;	/* Overrun errors */ 
	ulong_t	etherUnderrunErrors;	/* Underrun errors */ 
	ulong_t	etherCollisions;	/* Total collisions */ 
	ulong_t	etherAbortErrors;	/* Transmits aborted at interface */ 
	ulong_t	etherCarrierLost;	/* Carrier sense signal lost */ 
	ulong_t	etherReadqFull;		/* STREAMS read queue full */ 
	ulong_t	etherRcvResources;	/* Receive resource alloc failure */ 
	ulong_t	etherDependent1;	/* Device dependent statistic */ 
	ulong_t	etherDependent2;	/* Device dependent statistic */ 
	ulong_t	etherDependent3;	/* Device dependent statistic */ 
	ulong_t	etherDependent4;	/* Device dependent statistic */ 
	ulong_t	etherDependent5;	/* Device dependent statistic */ 
} DL_etherstat_t; 
 
/* 
 * Interface statistics compatible with MIB II SNMP requirements 
 */ 
typedef struct { 
	int	ifIndex;	/* ranges between 1 and ifNumber */ 
	int	ifDescrLen;	/* len of desc. following this struct */ 
	int	ifType;		/* type of interface */ 
	int	ifMtu;		/* datagram size that can be sent/rcv */ 
	ulong_t	ifSpeed;	/* estimate of bandwidth in bits PS */ 
	uchar_t	ifPhyAddress[DL_MAC_ADDR_LEN];/* Ethernet Address */ 
	int	ifAdminStatus;	/* desired state of the interface */ 
	int	ifOperStatus;	/* current state of the interface */ 
	ulong_t	ifLastChange;	/* sysUpTime when state was entered */ 
	ulong_t	ifInOctets;	/* octets received on interface */ 
	ulong_t	ifInUcastPkts;	/* unicast packets delivered */ 
	ulong_t	ifInNUcastPkts;	/* non-unicast packets delivered */ 
	ulong_t	ifInDiscards;	/* good packets received but dropped */ 
	ulong_t	ifInErrors;	/* packets received with errors */ 
	ulong_t	ifInUnknownProtos;	/* packets recv'd to unbound proto */ 
	ulong_t	ifOutOctets;	/* octets transmitted on interface */ 
	ulong_t	ifOutUcastPkts;	/* unicast packets transmitted */ 
	ulong_t	ifOutNUcastPkts;	/* non-unicast packets transmitted */ 
	ulong_t	ifOutDiscards;	/* good outbound packets dropped */ 
	ulong_t	ifOutErrors;	/* number of transmit errors */ 
	ulong_t	ifOutQlen;	/* length of output queue */ 
	DL_etherstat_t ifSpecific;	/* ethernet specific stats */ 
} DL_mib_t; 

The values in the MIB are compatible with those needed by the SNMP protocol.

The ifDescrLen field shows the length of the null-terminated description string that immediately follows the DL_mib_t structure.

There are three fields in the MIB that are specific to the odi driver. The ifSpecific.etherDependent1 field tracks the number of times the transceiver failed to transmit a collision signal after transmission of a packet. The ifSpecific.etherDependent2 field contains the number of collisions that occurred after a slot time (out of window collisions). The ifSpecific.etherDependent3 field tracks the number of times a transmit interrupt timeout condition occurred.

DLIOCSMIG

Allows a privileged process to initialize the values in the MIB (the DL_mib_t structure). A process cannot use this ioctl to change the ifPhyAddress, the ifDescrLen, or the text of the description fields.

DLIOCGENADDR

Returns the Ethernet address in network order.

DLIOCGLPCFLG

Returns the state of the local packet copy flag in the ioc_rval of the iocblk structure. The local copy flag determines if packets looped back by the driver should also be sent to the network. A non-zero value indicates that frames should also be sent to the network after being looped back. The default value of this flag is zero.

DLIOCSLPCFLG

Allows a privileged process to set the local packet copy flag, causing all packets looped back by the driver to be sent to the network as well.

DLIOCGPROMISC

Returns the value of the promiscuous flag in the ioc_rval of the iocblk structure. A non-zero value indicates that the Ethernet interface will receive all frames on the network. The default value of this flag is zero.

DLIOCSPROMISC

Allows a privileged process to toggle the current state of the promiscuous flag. When the flag is set, the driver captures all frames from the network. Processes that are bound to a promiscuous SAP, or to a SAP that matches the type field of the received frame, receive a copy of the frame.

DLIOCGETMULTI

Returns a list of multicast addresses (if it exists).

DLIOCADDMULTI

Allows a privileged process to add a new multicast address and enable its reception. A 6-byte buffer pointing to the multicast address must be passed as the parameter.

DLIOCDELMULTI

Allows a privileged process to delete a multicast address by passing a 6-byte multicast address as the parameter.

DLIOCRAWMODE

Allows a Token Ring privileged process to identify itself as a ``raw'' upstream module. This allows an upstream module to transmit a valid MAC frame using a DL_UNITDATA_REQ/IND message.

DLIOCLLC2MODE

Allows a privileged process to identify itself as a ``llc2'' upstream module. This allows a upstream module to transmit a valid LLC Type 2 (connection oriented) frame via a DL_UNITDATA_REQ/IND message.

Errors

ENXIO

Invalid major number or board is not installed.

ECHRNG

No minor devices left if configured as a cloned device. Increase HSM_nsaps in /etc/conf/pack.d/HSM/space.c. Invalid minor device number if configured as a non-clone device.

ENOENT

Selected NIC was found in the device database.

ENODEV

An attempt was made to initialize the boards but it failed.

ENOMEM

Not enough memory left in the system.

EPERM

An ioctl was made without the appropriate privilege.

EINVAL

An ioctl was made that did not supply a required input or output buffer.

The odi driver also can return the following errors using the DLPI DL_ERROR_ACK service primitive.

DL_NOTSUPPORTED

Requested service primitive is not supported.

DL_BADPRIM

Unknown service primitive was requested.

DL_OUTSTATE

DL_BIND_REQ was issued when the Stream was bound, or DL_UNBIND_REQ or DL_UNITDATA_REQ was issued when the Stream was not bound.

DL_ACCESS

An attempt was made to bind to PROMISCUOUS_SAP with insufficient privilege.

DL_BOUND

The requested SAP is already bound. A privileged process may bind to an already bound SAP.

DL_NOTINIT

DL_UNITDATA_REQ was made on a NIC that has gone offline because of an error.

DL_BADDATA

DL_UNITDATA_REQ was made with a data size that was either larger than the SPDU maximum or smaller than the SPDU minimum.

Files

/dev/HSM_

/etc/conf/pack.d/HSM/space.c

/etc/conf/sdevice.d/HSM

/etc/conf/mtune.d/lsl

/etc/conf/mtune.d/msm

/etc/conf/mtune.d/odisr

/etc/conf/dtune.d/lsl

/etc/conf/dtune.d/msm

/etc/conf/dtune.d/odisr

/stand/resmgr