odi(7) odi(7)
NAME
odi - ODI (Open DataLink Interface)
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
The vendor-supplied Netware Open DataLink Interface (ODI)
compliant Network Interface Card (NIC) drivers are inputs to
the process of transmogrification, which produces Data Link
Provider Interface (DLPI) compliant drivers which are
functionally equivalent to the original ODI drivers. (The ODI
drivers must comply with Revision 3.1 or Revision 3.2 of the
NetWare Open DataLink Interface specification.) The resulting
DLPI drivers are STREAMS-based and support the Logical Link
Control (LLC) protocol.
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
Copyright 1994 Novell, Inc. Page 1
odi(7) odi(7)
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 Tokenring UnixWare supports MAC type DL_TPR plus LLC2 MODE
and RAW MODE pass-thru interfaces, provider style DL_STYLE1,
and frame types TOKEN-RING and TOKEN-RING_SNAP.
The odi driver can operate as 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 field 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. The PROMISCUOUS_SAP matches all incoming
frames.
A privileged process may 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
Copyright 1994 Novell, Inc. Page 2
odi(7) odi(7)
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
The following ioctls are supported:
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 */
Copyright 1994 Novell, Inc. Page 3
odi(7) odi(7)
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 (that is, 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
Copyright 1994 Novell, Inc. Page 4
odi(7) odi(7)
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 tokenring privileged process to identify itself
as a "raw" upstream module. This allows a upstream
module to transmit a valid MAC frame via a
DL_UNITDATA_REQ/IND message.
Copyright 1994 Novell, Inc. Page 5
odi(7) odi(7)
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
The odi driver can return the following error codes:
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
and/or output buffer.
The odi driver also can return the following errors via 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.
Copyright 1994 Novell, Inc. Page 6
odi(7) odi(7)
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
REFERENCES
Copyright 1994 Novell, Inc. Page 7