Man page of lpfc

# man lpfc
Reformatting page. Please Wait... done

Devices lpfc(7D)

NAME
lpfc - Emulex LightPulse Fibre Channel FCP/SCSI host bus
adapter driver

SYNOPSIS
pci10df,1ae5@slot pci10df,f700@slot pci10df,f800@slot
pci10df,f900@slot

AVAILABILITY
SPARC and x86 Edition

DESCRIPTION
The lpfc host bus adapter driver provides an interface
between the Emulex LightPulse Family of Fibre Channel PCI
host bus adapters and Solaris running on platforms that
offer PCI support.

The driver is composed of two parts. One part is lpfc, a
Solaris SCSA driver providing both low level support for the
host bus adapter and FCP support. The FCP protocol emulates
SCSI-3 on top of Fibre Channel. Thus, FCP disk drives
appear to be SCSI disk drives from the standpoint of a host.

The second part of the driver is lpfn, which provides IP
networking support. The IP driver, lpfn, is briefly men-
tioned in this manual page; see lpfn(7D) for additional
details.

The lpfc driver can be loaded by itself; lpfn, which relies
on functionality in lpfc, automatically loads lpfc. The
driver module as a whole, including both FCP and IP support,
is referred to as lpfc. The driver can be configured to
support FCP by itself, IP by itself or FCP and IP together.
The default during installation is to support both FCP and
IP; this choice can be changed in the driver's configuration
file (see below).

Fibre Channel is an interconnect offering high throughput
and low latency across copper and optical media at distances
ranging up to 10 kilometers. Fibre Channel configurations
include point-to-point, loop (up to 126 devices) and fabric
(general switching network). Fibre Channel offers emulation
modes for SCSI and IP; the former is called FCP and the
latter is called IPP. Note that SCSI disk drives can not be
connected directly to a Fibre Channel; a Fibre Channel
interface is considerably different from a SCSI interface.

The Emulex LightPulse mediates between a host's PCI bus and
the Fibre Channel itself.

This driver supports the LightPulse family, running FCP and
IP.

SunOS 5.8 Last change: 25 March 1999 1

Devices lpfc(7D)

FCP DRIVER
The lpfc Host Bus Adapter driver is an SCSA compliant nexus
driver for the LightPulse. The lpfc driver provides basic
support for LightPulse hardware. Functions include adapter
initialization, frame transmit and receive, and error
recovery and reporting. Multiple LightPulse adapters
installed within the system are supported by the driver.
The lpfc driver supports the standard functions provided
by the SCSA interface. The driver supports tagged and
untagged queuing and auto request sense. Other SCSI proper-
ties, such as fast and wide, are irrelevant to Fibre Channel
and hence are ignored. Linked commands are not supported.

FCP CONFIGURATION
Most configuration options are addressed in the General Con-
figuration section, below. However, the target driver may
need to be configured to probe for additional targets on
Fibre Channel. The following discussion applies only when
using FCP functionality in lpfc.

Solaris target drivers must be instructed which disks to
probe for at boot time. These instructions are contained in
a configuration file specific to each target driver. On
SPARC, the target driver is called sd; on x86, the target
driver is called cmdk. The configuration files are, respec-
tively, sd.conf and cmdk.conf and are usually found in
/kernel/drv. There will only be one of these two target
drivers on your system. See the driver.conf(4) man page for
additional details.

Each disk drive on the Fibre Channel must have an entry in
sd.conf or cmdk.conf. The system administrator may have to
define additional targets and Logical Unit Numbers (LUNs) in
these files. For FCP when using arbitrated loop, there can
be up to 126 targets, with a maximum of 32 LUNs per target.
The installation procedure for lpfc automatically updates
sd.conf or cmdk.conf to search for Fibre Channel disk
drives. The instructions added to the configuration file
look like this:

name="sd" parent="lpfc" target=0 lun=0;

(On x86, you will see name="cmdk".)

The lpfc installation procedure adds one line to the target
driver configuration file for the first 126 targets. Up to
512 targets can be supported. However, no lines were
automatically added for every possible LUN, as 4032 entries
would be required. Instead, the default configuration only
searches for devices at LUN 0.

SunOS 5.8 Last change: 25 March 1999 2

Devices lpfc(7D)

If you want to use disks (e.g., RAID arrays) with non-zero
LUNs, or more then 126 targets, simply add lines to the tar-
get driver configuration file specifying the desired target
ID and LUN(s). For example, including the follwoing lines
in the system's target driver configuration file:

name="sd" parent="lpfc" target=127 lun=0;
name="sd" parent="lpfc" target=127 lun=1;
name="sd" parent="lpfc" target=127 lun=2;
name="sd" parent="lpfc" target=127 lun=3;

(On x86, you will see name="cmdk".)

We use the parent keyword to ensure that Solaris specifi-
cally probes the lpfc driver for the specified targets and
LUNs. Note that changes to a target driver's configuration
file will only take effect after the system has been
rebooted.

Refer to scsi_hba_attach(9F) for details on setting indivi-
dual SCSI properties.

GENERAL CONFIGURATION
All the variables that control driver initialization may be
found in a file called lpfc.conf. This file is located in
the installation directory containing the binary for the
driver itself, lpfc. Typically, this directory will be
/kernel/drv. Other information is obtained dynamically from
probing the attached Fibre Channel. The variables described
in this section are the ones a system administrator is most
likely to be concerned with.

Important: These values are set per adapter; e.g., setting
num-iocbs to 300 allocates 300 I/O control blocks for every
LightPulse present in the host machine. In the descriptions
below, the annotation (F) means that the variable only has
meaning when FCP functionality is enabled in lpfc. Vari-
ables lacking an annotation have meaning for the entire
driver. A boolean variable should be set to either 0
(FALSE) or 1 (TRUE), although any non-zero value will suf-
fice for TRUE. When a value can be set to infinity, we mean
that it can be set as high as the largest possible unsigned
integer value.

ack0
If ack0 is 1, the adapter will try to use ACK0 when
running Class 2 traffic to a device. If the device
doesn't support ACK0, then the adapter will use ACK1.
If ack0 is 0, only ACK1 will be used when running
Class2 traffic.

SunOS 5.8 Last change: 25 March 1999 3

Devices lpfc(7D)

automap
If automap is 1, SCSI IDs for all FCP nodes without
persistent bindings will be automatically generated. If
FCP devices are added to or removed from the Fibre
Channel network when the system is down, there is no
guarantee that these SCSI IDs will remain the same when
the system is booted again. If one of the FCP binding
methods below is specified, then automap devices will
use the same mapping to try to preserve SCSI IDs
between link down and link up. If automap is 0, only
devices with persistentbindings will be recognized by
the system.

check-cond-err
The driver will treat ckeck condition 0x44, Internal
Target Failure, check condition 0x25, Logical Unit Not
Supported and check condition 0x20, Invalid Command
Operation Code, as FCP RSP errors.

delay-rsp-err
The driver will delay FCP RSP errors being returned to
the upper SCSI layer based on the no-device-delay con-
figuration parameter.

dqfull-throttle
This variable causes lpfc to decrement a LUNs throttle
(maximum queue depth) if a queue full condition is
received from the target. The queue depth will be
decremented down to a minimum of 3. The only way to
restore the queue depth (besides rebooting), back to
the original LUN throttle, is by running the command
/usr/sbin/lpfc/resetqdepth X. This will restore the LUN
throttle of all LUNs for adapter X back to the original
value.

fcp-bind-WWNN
Setup persistent FCP binding based on a target device's
WWNN. THis binding guarantees that target assignments
will be preserved between reboots. The format for a
bind entry is "NNNNNNNNNNNNNNNN:lpfcXtY" where
NNNNNNNNNNNNNNNN is a 16 digit representation of the
targets WorldWide Node Name, X is the driver instance
number and Y is the target assignment. Multiple entries
must be separated by a comma (,) with the last entry
terminated with a semi-colon (;). Target assignments,
with all supported LUNs must also be configured in
sd.conf or st.conf. A sample entry follows:

fcp-bind-WWNN="20000020370c396f:lpfc1t0",
"20000020370c27f7:lpfc0t2";

SunOS 5.8 Last change: 25 March 1999 4

Devices lpfc(7D)

fcp-bind-WWPN
Setup persistent FCP binding based on a target device's
WWPN. THis binding guarantees that target assignments
will be preserved between reboots. The format for a
bind entry is "NNNNNNNNNNNNNNNN:lpfcXtY" where
NNNNNNNNNNNNNNNN is a 16 digit representation of the
targets WorldWide Port Name, X is the driver instance
number and Y is the target assignment. Multiple entries
must be separated by a comma (,) with the last entry
terminated with a semi-colon (;). Target assignments,
with all supported LUNs must also be configured in
sd.conf or st.conf. A sample entry follows:

fcp-bind-WWPN="21000020370c396f:lpfc1t0";

fcp-bind-DID
Setup persistent FCP binding based on a target device's
Port ID. THis binding guarantees that target assign-
ments will be preserved between reboots. The format for
a bind entry is "NNNNNN:lpfcXtY" where NNNNNN is a 6
digit representation of the targets Port ID, X is the
driver instance number and Y is the target assignment.
Multiple entries must be separated by a comma (,) with
the last entry terminated with a semi-colon (;). Target
assignments, with all supported LUNs must also be con-
figured in sd.conf or st.conf. A sample entry follows:

fcp-bind-DID="0000ef:lpfc0t0";

fcp-class
The lpfc driver is capable of transmitting FCP data in
Class 2 or Class3. the lpfc driver defaults to using
Class 3 transmission.

fcpfabric-tmo
Extra timeout value, in seconds, to be applied to each
FCP command sent. When connecting through a large
fabric, certain devices may require a longer timeout
value.

fcp-on
Enable the FCP functionality of lpfc. This variable is
a Boolean; Zero disables FCP while non-zero enables it.

link-speed
This causes lpfc to set the adapter link speed to
auto-detect (0), 1 gigabit (1) or 2 gigabits (2). This
setting only applies to the LightPulse 9002 adapter.

SunOS 5.8 Last change: 25 March 1999 5

Devices lpfc(7D)

linkdown-tmo
How long the driver will wait (1 to 255 seconds) before
declaring the Fibre Channel link to be down. Commands
waiting to be serviced will be aborted. For instance,
FCP commands will be returned to the target driver. The
lower this value is, the quicker the driver will fail
commands back to the upper levels. There is tradeoff
here: small vaules risk retrying commands when link is
bouncing, while large values risk delaying failover in
a redundant loop environment. Setting linkdown-tmo to
0 will cause all commands issued to the device driver
to be held internally (never failed) until the link
comes back up.

lun-queue-depth
The driver uses this value as the default limit for the
number of simultaneous commands to issue to a single
logical unit on a single target on the loop. A single
logical unit will never be sent more commands than
allowed by lun-queue-depth; however, less may be sent
when sd_max_throttle or tgt-queue-depth is reached for
the entire target.

lpfcNtM-lun-throttle
The maximum number of outstanding commands to permit
for any logical unit on a specific target. This value
overrides lun-queue-depth.

lpfcNtM-tgt-throttle
The maximum number of outstanding commands to permit
for any target, including all LUNs on that target. This
value overrides tgt-queue-depth.

network-on
This variable controls whether lpfc provides IP net-
working functionality over Fibre Channel. This vari-
able is a Boolean: when zero, IP networking is dis-
abled; when non-zero, IP networking is enabled.

log-only
When set to 1, log messages are only logged to syslog.
When set to 0, log messages are also printed on the
console.

log-verbose
(bit mask) When set to non-zero this variable causes
lpfc to generate additional messages concerning the
state of the driver and the I/O operations it carries
out. These messages may go to the system console
and/or the system log file, /var/adm/messages.

SunOS 5.8 Last change: 25 March 1999 6

Devices lpfc(7D)

no-device-delay
This variable [0 to 30] - determines the length of the
interval between deciding to fail an I/O because there
is no way to communicate with its particular device
(e.g., due to device failure or device removal) and
actually failing the command. A value of zero implies
no delay whatsoever. This delay is specified in
seconds. A minimum value of 1 (1 second) is recommanded
when communicating with any Tachyon based device.

nodev-holdio
This variable controls if I/O errors are held by the
driver if a device on the loop disappears. If set, I/O
errors will be held until the device returns back to
the loop (potentially indefinitely). The upper sd layer
may retry the command once the error is returned.

nodev-tmo
The variable controls how long I/O errors are held by
the driver if a device on the loop disappears. If set,
I/O errors will be held for the specified number of
seconds. The upper sd layer may retry the command once
the error is returned.
num-bufs
This variable specifies the number of ELS command
buffers to allocate. These buffers are used for Fibre
Channel Extended Link Services (ELS), and one for each
FCP command issued in SLI-2 mode. If you want to queue
lots of FCP commands to the adapter, then you should
increase num-bufs for better performance. These buffers
consume physical memory and are also used by the device
driver to process loop initialization and re-discovery
activities. Important: The driver must always be con-
figured with at least several dozen ELS command
buffers; we recommend at least 256.

num-iocbs
This variable indicates the number of Input/Output con-
trol block (IOCB) buffers to allocate. IOCBs are
internal data structures used to send and receive I/O
requests to and from the LightPulse Sbus hardware. Too
few IOCBs can temporarily prevent the driver from com-
municating with the adapter, thus lowering performance.
(This condition is not fatal.) If you run heavy IP
traffic, you should increase num-iocbs for better per-
formance.

scan-down
There are three scanning algorithms used to map an ALPA
to a SCSI ID in a private loop. Refer to the "informa-
tive annex" of the FC-AL profile, which describes the
algorithm for this translation. Scan-down values 0 and

SunOS 5.8 Last change: 25 March 1999 7

Devices lpfc(7D)

1 do not apply if a loop map is obtained. See the FC-
AL profile for the definition of a loop map. If the
adapter is not attached to a fabric, these parameters
do not apply (use persistent binding). If scan-down is
1, SCSI IDs are scanned starting from ALPA 0xEF through
ALPA 0x01. If scan-down is 0, SCSI IDs are scanned
starting fro ALPA 0x1 on up. If scan-down is 2
(default value), SCSI IDs are hard coded based on the
ALPA (0xEF=SCSI ID 0, 0xE*=SCSI ID 1.....). This param-
eter is userd to maintain backward compatibility with
the SCSI ID assignments of the 2.05 Solaris driver.

tgt-queue-depth
The driver uses this value as the default limit for the
number of simultaneous commands to issue to a single
target on the loop. A value of 0 causes no target
throttling to occur. A single target will never be
send more commands than allowed by tgt-queue-depth;
however, less may be sent when sd_max_throttle is
reached for the entire target.

topology
This variable controls the Fibre Channel topology
expected by lpfc at boot time. Fibre Channel offers
point-to-point, fabric, and arbitrated loop topologies.
This variables encodes these topologies as follows:

0 Attempt loop mode, if it fails attempt point-to-point mode
2 Attempt point-to-point only
4 Attempt loop only
6 Attempt point-to-point mode, if it fails attempt loop mode

To make the adapter operate as an N_Port, select
point-to-point mode (used for N_Port to F_Port, and
N_Port to N_Port connections). To make the adapter
operate in a Fibre Channel loop as an NL_Port, select
loop mode (used for private loop and public loop topo-
logies). The driver will reject an attempt to set the
topology to a value not in the above list. The auto-
topology setting (0 and 6) will not work unless the
adapter is using firmware version 3.20 or higher.

use-adisc
The variable controls the ELS command used for FCP
address authentication during discovery. If set, ADISC
is used, otherwise, PLOGI is used.

use-lomempages
This variable applies only to x86 platforms. The set-
ting of this variable can affect whether lpfc runs
correctly on an x86 host. The Solaris DDI/DKI requires
that kernel memory be allocated using special

SunOS 5.8 Last change: 25 March 1999 8

Devices lpfc(7D)

primitives if that memory may be the target of a DMA
operation. On the x86, this memory comes from a spe-
cial low memory pool that is guaranteed to be safe for
DMA operations across all x86 platforms. (Some plat-
forms do not correctly handle DMA operations on physi-
cal memory above the 16 megabyte boundary.) Unfor-
tunately, the size of the low memory pool is very lim-
ited; in fact, the standard Solaris releases default to
a size of 36 pages in this pool. While the size of the
pool can be increased, on most x86 systems a reasonable
alternative is to not use this pool at all. On these
systems, ordinary memory works correctly as a target
for DMA operations. As lpfc is distributed, we set the
value of this variable to 0, disabling the use of the
low memory pool. If you suspect that your x86 platform
can't handle arbitrary DMA correctly above the 16MB
boundary, set this variable to 1; you must also
increase the size of the low memory pool. Refer to the
release notes for more information.

zone-rscn
If zone-rscn is 1, the driver will check the NameServer
data to see if an N_Port ID received in an RSCN is per-
tinent to this adapter. This behavior is necessary
when running soft zoning in a Brocade fabric. If
zone-rscn is 0, the RSCN is assumed to apply to this
adapter, and no NameServer query is performed.

BUGS
Refer to the release notes for information about known bugs.

FILES
/kernel/drv/lpfc ELF Kernel Module 32b mode
/kernel/drv/sparcv9/lpfc ELF Kernel Module 64b mode
/kernel/drv/lpfc.conf configuration file for the
entire lpfc driver
/kernel/drv/cmdk.conf (x86) Target driver configura-
tion file
/kernel/drv/sd.conf (SPARC) Target driver confi-
guration file
/etc/system System-wide configuration file

SEE ALSO
prtconf(1M), driver.conf(4), scsi_abort(9F),
scsi_device(9S), scsi_extended_sense(9S),
scsi_hba_attach(9F), scsi_ifgetcap(9F), scsi_inquiry(9S),
scsi_pkt(9S) scsi_reset(9F), scsi_transport(9F), pkgadd(1M),

Writing Device Drivers

OpenBoot Command Reference

SunOS 5.8 Last change: 25 March 1999 9

Devices lpfc(7D)

ANSI Small Computer System Interface-3 (SCSI-3)

LightPulse PCI Host Adapter User Guide

LightPulse Host Adapter Release Notes

lpfc: LightPulse Solaris HBA Driver Release Notes

SunOS 5.8 Last change: 25 March 1999 10