'\" te
.\"  Copyright (c) 2009, 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 IB 7D "Jan 26, 2009"
.SH NAME
ib \- InfiniBand Bus Nexus Driver
.SH DESCRIPTION
.sp
.LP
The \fBib\fR (IB nexus) driver is a pseudo nexus driver that supports
enumeration of port devices, VPPA (Virtual Physical Point Attachment), HCA_SVC
(HCA  Service) devices, and I/O controllers (IOC) on the InfiniBand fabric that
are visible to the host and provides interfaces to \fBcfgadm_ib\fR(1M) to
manage hot-plugging of IB devices. The \fBib\fR nexus driver enumerates the
port device, VPPA devices and HCA_SVC devices based on entries specified in the
\fBib.conf\fR file. IOC devices are enumerated on demand. The IB  nexus driver
uses InfiniBand Device Manager services (\fBibdm\fR(7D)) to enumerate port
devices, VPPA devices, HCA_SVC devices, and IOCs on the IB fabric.
.SH CONFIGURATION
.sp
.LP
You configure the \fBib\fR driver by defining properties in the \fBib.conf\fR
file. The IB nexus driver supports the following properties:
.sp

.sp
.TS
box;
l | l | l
l | l | l .
PROPERTY NAME	DEFAULT	POSSIBLE VALUES
_
port-svc-list	\fB""\fR	T{
List of service names,  for example:  srv
T}
_
vppa-svc-list	\fB""\fR	List of service names, for example: ipib
_
hca-svc-list	\fB""\fR	T{
List of service names, for example: hca_nfs
T}
.TE

.sp
.LP
The \fBport-svc-list\fR property defines the list of port communication service
names per port. The IB nexus driver creates a device instance for each entry in
this property per Host Channel Adapter (\fBHCA\fR) port. The \fBib.conf\fR file
contains a \fBport-svc-list=""\fR entry by default. You update
\fBport-svc-list\fR with service names you want to add to the system.
.sp
.LP
The \fBvppa-svc-list\fR property defines the list of \fBVPPA\fR communication
service names per port per partition key. The IB nexus driver creates a device
instance for each entry in this property per Host Channel Adapter (\fBHCA\fR)
port. The \fBib.conf\fR file contains a \fBvppa-svc-list=""\fR entry by
default. You update \fBvppa-svc-list\fR with service names you want to add to
the system.
.sp
.LP
The \fBhca-svc-list\fR property defines the list of HCA_SVC communication
service names per HCA. The IB nexus driver creates a device instance for each
entry in this property per Host Channel Adapter (HCA). The \fBib.conf\fR file
contains a \fBhca-svc-list=""\fR  entry by  default. You update
\fBhca-svc-list\fR with service names you want to add to the system.
.sp
.LP
The service name specified in \fBport-svc-list\fR, \fBvppa-svc-list\fR and
\fBhca-svc-list\fR must be  unique, be a maximum of four characters long, and
is limited to digits 0-9 and letters a-z and A-Z.
.sp
.LP
IOC drivers (which are parented by the IB nexus driver) may themselves
have .conf files. To distinguish those cases from pseudo drivers parented by IB
nexus, such drivers should include the \fB"ib-node-type"\fR property with value
\fBmerge\fR in the IOC \fBdriver.conf\fR file. That property ensures that
properties from the .conf file are merged with other properties found through
hardware probing.
.SH EXAMPLES
.sp
.LP
Example 1: A sample \fBib.conf\fR file with one  service name entry for PORT
communication services.
.sp
.in +2
.nf
    #
    # Copyright 2001-2003 Sun Microsystems, Inc.  All rights reserved.
    # Use is subject to license terms.
    #
    port-svc-list=""
    vppa-svc-list="";
    hca-svc-list="";
.fi
.in -2

.sp
.LP
In Example 1, the IB nexus driver does not create any port/vppa/hca_svc device
instances.
.sp
.LP
Example 2: A sample \fBib.conf\fR file with one entry for \fB"srv"\fR service:
.sp
.in +2
.nf

   port-svc-list="srv"
   vppa-svc-list="";
   hca-svc-list="";
.fi
.in -2

.sp
.LP
The IB nexus driver creates one \fBsrv\fR service instance for every \fBHCA\fR
port that exists on the host. For example, if there are two \fBHCA\fRs, each
with two ports on the host, the IB nexus driver creates four instances of the
\fBsrv\fR service.
.sp
.LP
Example 3: A sample \fBib.conf\fR file with one  service name entry for
each of Port and VPPA  communication services:
.sp
.in +2
.nf

   port-svc-list="srv"
   vppa-svc-list="ipib";
   hca-svc-list="";
.fi
.in -2

.sp
.LP
If there are two \fBHCA\fRs in the system with two ports each and each port has
two  valid PKEY values, the IB  nexus driver creates four instances of  srv
service (one for each port).  It also creates eight instances of \fBipd\fR
service (one per each port/PKEY combination).
.sp
.LP
Example 4: A sample \fBib.conf\fR file with one service name entry for     each
of Port, VPPA and HCA_SVC communication services:
.sp
.in +2
.nf

   port-svc-list="srv";
   vppa-svc-list="ipib";
   hca-svc-list="hca_nfs";
.fi
.in -2

.sp
.LP
The IB nexus driver creates one instance of hca_nfs service for each HCA in the
system.
.sp
.LP
Example 5: IOC \fBdriver .conf\fR
.sp
.in +2
.nf
 ib-node-type="merge";
 enable-special-mode="on";
.fi
.in -2

.SH FILES
.sp
.ne 2
.na
\fB\fB/kernel/drv/ib\fR\fR
.ad
.RS 26n
32-bit x86 ELF kernel module
.RE

.sp
.ne 2
.na
\fB\fB/kernel/drv/amd64/ib\fR\fR
.ad
.RS 26n
64-bit x86 ELF kernel module
.RE

.sp
.ne 2
.na
\fB\fB/kernel/drv/sparcv9/ib\fR\fR
.ad
.RS 26n
64-bit SPARC ELF kernel module
.RE

.sp
.ne 2
.na
\fB\fB/kernel/drv/ib.conf\fR\fR
.ad
.RS 26n
driver configuration file
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for a description of the following attribute:
.sp

.sp
.TS
box;
l | l
l | l .
ATTRIBUTE  TYPE	ATTRIBUTE VALUE
_
Architecture	SPARC, x86
_
Interface Stability	Consolidation Private
.TE

.SH SEE ALSO
.sp
.LP
\fBcfgadm_ib\fR(1M), \fBdriver.conf\fR(4), \fBib\fR(4), \fBattributes\fR(5),
\fBibcm\fR(7D), \fBibdm\fR(7D), \fBibtl\fR(7D)
.sp
.LP
\fIWriting Device Drivers\fR
.sp
.LP
\fIInfiniBand Architecture Specification, Volume 1: Release 1.1\fR
.sp
.LP
\fISystem Administration Guide: Basic Administration\fR
.SH DIAGNOSTICS
.sp
.LP
In addition to being logged, the following messages may appear on the system
console. All messages are formatted in the following manner:
.sp
.in +2
.nf
ib: WARNING: Error message...
.fi
.in -2
.sp

.sp
.ne 2
.na
\fBunit-address property in \fB%s.conf\fR not well-formed.\fR
.ad
.sp .6
.RS 4n
The \fBdriver.conf\fR file does not have a valid \fB"unit-addr"\fR property
defined. This property is an array of strings.
.RE

.sp
.ne 2
.na
\fBcannot find unit-address in \fB%s.conf\fR.\fR
.ad
.sp .6
.RS 4n
The \fBdriver.conf\fR file does not have a valid \fB"unit-addr"\fR property
defined. This property is an array of strings.
.RE

.sp
.ne 2
.na
\fBWaiting for Port %d initialization.\fR
.ad
.sp .6
.RS 4n
Waiting for port initialization from subnet manager.
.RE