'\" te
.\"  Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH IBD 7D "Jul 20, 2007"
.SH NAME
ibd \- Infiniband IPoIB device driver
.SH SYNOPSIS
.LP
.nf
\fB/dev/ibd*\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBibd\fR driver implements the IETF IP over Infiniband protocol and
provides IPoIB service for all IBA ports present in the system.
.sp
.LP
The \fBibd\fR driver is a multi-threaded, loadable, clonable, STREAMS hardware
driver supporting the connectionless Data Link Provider Interface,
\fBdlpi\fR(7P)). The \fBibd\fR driver provides basic support for the IBA
Unreliable Datagram Queue Pair hardware. Functions include QP initialization,
frame transmit and receive, multicast and promiscuous mode support, and
statistics reporting.
.sp
.LP
Use the cloning, character-special device \fB/dev/ibd\fR to access all
\fBibd\fR devices installed within the system.
.sp
.LP
The \fBibd\fR driver is dependent on GLD, a loadable kernel module that
provides the \fBibd\fR driver with the DLPI and STREAMS functionality required
of a LAN driver. Except as noted in the Application Programming Interface
section of this manpage, see \fBgld\fR(7D) for more details on the primitives
supported by the driver. The GLD module is located at
\fB/kernel/misc/sparcv9/gld\fR on 64 bit systems and at \fB/kernel/misc/gld\fR
on 32 bit systems.
.sp
.LP
The \fBibd\fR driver expects certain configuration of the IBA fabric prior to
operation (which also implies the SM must be active and managing the fabric).
Specifically, the IBA multicast group representing the IPv4 limited broadcast
address 255.255.255.255 (also defined as broadcast-GID in IETF documents) must
be created prior to initializing the device. IBA properties (including mtu,
qkey and sl) of this group is used by the driver to create any other IBA
multicast group as instructed by higher level (IP) software. The driver probes
for the existance of this broadcast-GID during \fBattach\fR(9E).
.SH APPLICATION PROGRAMMING INTERFACE (DLPI)
.sp
.LP
The values returned by the driver in the DL_INFO_ACK primitive in response to
your DL_INFO_REQ are:
.RS +4
.TP
.ie t \(bu
.el o
Maximum SDU is the MTU associated with the broadcast-GID group, less the 4 byte
IPoIB header.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Minimum SDU is 0.
.RE
.RS +4
.TP
.ie t \(bu
.el o
dlsap address length is 22.
.RE
.RS +4
.TP
.ie t \(bu
.el o
MAC type is DL_IB.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The sap length value is -2, meaning the physical address component is followed
immediately by a 2-byte sap component within the DLSAP address.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Broadcast address value is the MAC address consisting of the 4 bytes of QPN
00:FF:FF:FF prepended to the IBA multicast address of the broadcast-GID.
.sp
Due to the nature of link address definition for IPoIB, the
DL_SET_PHYS_ADDR_REQ DLPI primitive is not supported.
.sp
In the transmit case for streams that have been put in raw mode via the
DLIOCRAW ioctl, the DLPI application must prepend the 20 byte IPoIB destination
address to the data it wants to transmit over-the-wire. In the receive case,
applications receive the IP/ARP datagram along with the IETF defined 4 byte
header.
.RE
.SH WARNING
.sp
.LP
This section describes warning messages that might be generated by the driver.
Please note that while the format of these messages may be modified in future
versions, the same general information will be provided.
.sp
.LP
While joining IBA multicast groups corresponding to IP multicast groups as part
of multicast promiscuous operations as required by IP multicast routers, or as
part of running \fBsnoop\fR(1M), it is possible that joins to some multicast
groups can fail due to inherent resource constraints in the IBA components. In
such cases, warning message similar to the following appear in the system log,
indicating the interface on which the failure occurred:
.sp
.in +2
.nf
NOTICE: ibd0: Could not get list of IBA multicast groups
NOTICE: ibd0: IBA promiscuous mode missed multicast group
NOTICE: ibd0: IBA promiscuous mode missed new multicast gid
.fi
.in -2

.sp
.LP
Also, if the IBA SM indicates that multicast trap support is suspended or
unavailable, the system log  contains a message similar to:
.sp
.in +2
.nf
NOTICE: ibd0: IBA multicast support degraded due to
unavailability of multicast traps
.fi
.in -2

.sp
.LP
And when the SM indicates trap support is restored:
.sp
.in +2
.nf
NOTICE: ibd0: IBA multicast support restored due to
availability of multicast traps
.fi
.in -2

.sp
.LP
Additionally, if the IBA link transitions to an unavailable state (that is, the
IBA link state becomes "Down," "Initialize" or "Armed") and then becomes active
again, the driver tries to rejoin previously joined groups if required. Failure
to rejoin multicast groups will trigger messages like:
.sp
.in +2
.nf
NOTICE: ibd0: Failure on port up to rejoin multicast gid
.fi
.in -2

.sp
.LP
If the corresponding HCA port is in the unavailable state defined above when
initializing an ibd interface using \fBifconfig\fR(1M), a message is emitted by
the driver:
.sp
.in +2
.nf
NOTICE: ibd0: Port is not active
.fi
.in -2

.sp
.LP
Further, as described above, if the broadcast-GID is not found, or the
associated MTU is higher than what the HCA port can support, the following
messages are printed to the system log:
.sp
.in +2
.nf
NOTICE: ibd0: IPoIB broadcast group absent
NOTICE: ibd0: IPoIB broadcast group MTU 4096 greater than port's
maximum MTU 2048
.fi
.in -2

.sp
.LP
In all cases of these reported problems when running \fBifconfig\fR(1M), it
should be checked that IBA cabling is intact, an SM is running on the fabric,
and the broadcast-GID with appropriate properties has been created in the IBA
partition.
.SH CONFIGURATION
.sp
.LP
The IPoIB service comes preconfigured on all HCA ports in the system. To turn
the service off, or back on after turning it off, refer to documentation in
\fBcfgadm_ib(1M)\fR.
.SH FILES
.sp
.ne 2
.na
\fB\fB/dev/ibd*\fR\fR
.ad
.RS 27n
special character device
.RE

.sp
.ne 2
.na
\fB\fB/kernel/drv/ib.conf\fR\fR
.ad
.RS 27n
configuration file to start IPoIB service
.RE

.sp
.ne 2
.na
\fB\fB/kernel/drv/sparcv9/ibd\fR\fR
.ad
.RS 27n
64-bit SPARC device driver
.RE

.sp
.ne 2
.na
\fB\fB/kernel/drv/amd64/ibd\fR\fR
.ad
.RS 27n
64-bit x86 device driver
.RE

.sp
.ne 2
.na
\fB\fB/kernel/drv/ibd\fR\fR
.ad
.RS 27n
32-bit x86 device driver
.RE

.SH SEE ALSO
.sp
.LP
\fBcfgadm\fR(1M), \fBcfgadm_ib(1M)\fR, \fBifconfig\fR(1M), \fBsyslogd\fR(1M),
\fBgld\fR(7D), \fBib\fR(7D), \fBkstat\fR(7D), \fBstreamio\fR(7I),
\fBdlpi\fR(7P), \fBattributes\fR(5), \fBattach\fR(9E)
.SH NOTES
.sp
.LP
IBD is a GLD-based driver and provides the statistics described by
\fBgld\fR(7D). Note that valid received packets not accepted by any stream
(long) will increase when IBD transmits broadcast IP packets. This happens
because the infiniband hardware copies and loops back the transmitted broadcast
packets to the source. These packets are discarded by GLD and are recorded
as 'unknowns'.