path: root/usr/src/man/man8/cfgadm_pci.8

'\" te
.\" Copyright (c) 2006, 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 CFGADM_PCI 8 "June 20, 2021"
.SH NAME
cfgadm_pci \- PCI, CompactPCI, and PCI Express Hotplug hardware specific
commands for cfgadm
.SH SYNOPSIS
.nf
\fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR]
     [\fB-o\fR \fIhardware_options\fR] \fB-c\fR \fIfunction\fR \fIap_id\fR [\fIap_id\fR]
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR]
     [\fB-o\fR \fIhardware_options\fR] \fB-x\fR \fIhardware_function\fR \fIap_id\fR
     [\fIap_id\fR]
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-s\fR \fIlisting_options\fR]
     [\fB-o\fR \fIhardware_options\fR] [\fB-l\fR [\fIap_id\fR | \fIap_type\fR]]
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-o\fR \fIharware_options\fR] \fB-t\fR \fIap_id\fR [\fIap_id\fR]
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-o\fR \fIhardware_function\fR] \fB-h\fR
     [\fIap_id\fR| \fIap_type\fR]
.fi

.SH DESCRIPTION
The PCI hardware specific library, \fB/usr/lib/cfgadm/pci.so.1\fR, provides the
support for hot plugging PCI, CompactPCI, and PCI Express adapter cards into
the respective hot pluggable slots in a system that is hot plug capable,
through the \fBcfgadm\fR command (see \fBcfgadm\fR(8)). Hot plug
administrative models between PCI, CompactPCI, and PCI Express remain the same
except where noted in this document.
.sp
.LP
For PCI Hot Plug, each hot plug slot on a specific PCI bus is represented by an
attachment point of that specific PCI bus.
.sp
.LP
An attachment point consist of two parts: a receptacle and an occupant. The
\fBreceptacle\fR under PCI hot plug is usually referred to as the physical hot
pluggable slot; and the \fBoccupant\fR is usually referred to as the PCI
adapter card that plugs into the slot.
.sp
.LP
Attachment points are named through \fBap_id\fRs. There are two types of
\fBap_id\fRs: logical and physical. The physical \fBap_id\fR is based on the
physical pathname, that is, \fB/devices/pci@1/hpc0_slot3\fR, whereas the
logical \fBap_id\fR is a shorter, and more user-friendly name. For PCI hot
pluggable slots, the logical \fBap_id\fR is usually the corresponding hot plug
controller driver name plus the logical slot number, that is,
\fBpci0:hpc0slot1\fR; PCI nexus driver, with hot plug controller driver named
\fBhpc\fR and slot number \fB1\fR. The \fBap_type\fR for Hot plug PCI is
\fBpci\fR.
.sp
.LP
Note that the \fBap_type\fR is not the same as the information in the
\fBType\fR field.
.sp
.LP
See the \fI\fR for a detailed description of the hot plug procedure.
.SS "PCI Express ap_id naming"
For attachment points located in a PCI Express hierarchy (that is, the parent
or an ancestor is a PCI Express device), including attachment points which are
not PCI Express devices themselves, the following naming scheme is used:
.sp
.in +2
.nf
Grammar:
   APID : absolute-slot-path

   absolute-slot-path : \fIslot-path\fR[\fI:slot-path\fR[\fI:slotpath\fR ...]]

   slot-path : [\fIfru-id\fR.]\fIslot-id\fR
           where \fIfru-id\fR indicates the chassis FRU, if any,
           containing the \fIslot-id\fR

   fru-id : \fIfru-type\fR[\fIserialid#\fR]
           where \fIfru-type\fR is "iob" for PCI Express expansion
           chassis, followed by its serial number \fIserialid#\fR,
           if available

    slot-id: \fIslot-name\fR | \fIdevice-type\fR \fIphysical-slot#\fR |\e
            \fInexus-driver-name\fR \fInexus-driver-instance\fR.\e
            \fIdevice-type\fR \fIpci-device-number\fR
.fi
.in -2
.sp

.sp
.LP
where \fIslot-name\fR is a name assigned by the platform or hardware itself;
\fIdevice-type\fR is either "pcie"for PCI Express devices or "pci" for PCI
devices; \fInexus-driver-name\fR is the driver name for the device component;
\fIphysical-slot#\fR is the hardware slot number; and \fIpci-device-number\fR
is the PCI device number in standard PCI nomenclature.
.sp
.LP
First, an \fIabsolute-slot-path\fR is constructed that attempts to describe the
attachment point's topological location in more physically identifiable terms
for the user. This \fIabsolute-slot-path\fR consists of \fIslot-path\fR
components each separated by a ":" (colon). The leaf or left-most
\fIslot-path\fR component describes the device of the attachment point itself
while its right adjacent \fIslot-path\fR component up to the right or top-most
\fIslot-path\fR component describes the parent up to the root devices,
respectively.
.sp
.LP
Each \fIslot-path\fR consists of a \fIslot-id\fR optionally preceded by an
\fIfru-id\fR, which indicates an expansion chassis containing the device
described by \fIslot-id\fR (detailed below). \fIfru-id\fR consists of
\fIfru-type\fR followed by an optional \fIserialid#\fR. \fIfru-type\fR is "iob"
for PCI Express expansion chassis types, while \fIserialid#\fR is either a
64-bit hexadecimal number indicating a raw serial number obtained from the
expansion chassis hardware, or a 4 upper-case ASCII character sequence for Sun
branded expansion chassis.
.sp
.LP
Each \fIslot-id\fR consists of one of three possible forms:
.sp
.ne 2
.na
\fBslot-id form (1)\fR
.ad
.sp .6
.RS 4n
\fIslot-names\fR
.RE

.sp
.ne 2
.na
\fBslot-id form (2)\fR
.ad
.sp .6
.RS 4n
\fIdevice-type\fR \fIphysical-slot#\fR
.RE

.sp
.ne 2
.na
\fBslot-id form (3)\fR
.ad
.sp .6
.RS 4n
\fInexus-driver-name\fR \fInexus-driver-instance\fR. \fIdevice-type\fR
\fIpci-device-number\fR
.RE

.sp
.LP
The precedence of which form to select flows from the lowest form number to the
highest form number, or from top to bottom as described above. If a form
cannot be successfully constructed, then the next numerically higher form is
attempted.
.sp
.LP
The \fIslot-names\fR in "slot-id form (1)" is taken from the "slot-names"
property of the corresponding node in the device tree and is a name assigned by
hardware or the platform. This format is not predefined or established.
.sp
.LP
In "slot-id form (2)", \fIdevice-type\fR indicates the device type of the
component's slot, and is either "pcie" for PCI Express or "pci" for PCI, while
\fIphysical-slot#\fR, take from the "physical-slot#" property of its
corresponding device node, indicates the hardware slot number of the component.
.sp
.LP
"slot-id form (3)" is used when all other forms cannot successfully be
constructed, and is considered to be the default form. \fInexus-driver-name\fR
is the component's driver name; \fInexus-driver-instance\fR is such driver's
instance; \fIdevice-type\fR is the same as described in form (2);
\fIpci-device-type\fR is the PCI device number as described and used for device
configuration cycles in standard PCI nomenclature.
.sp
.LP
In summary of the \fIslot-path\fR component, expanding the optional FRU
component that may precede it, \fIslot-path\fR will consist one of the
following forms in order:
.sp
.in +2
.nf
(1) [ iob[serialid#]. ] slot-names
(2) [ iob[serialid#]. ] device_type physical_slot#
(2) [ iob[serialid#]. ]
          nexus-driver-name nexus-driver-instance.
          device_type pci-device-number
.fi
.in -2
.sp

.sp
.LP
Lastly, the final form of the actual \fIap_id\fR name used in \fBcfgadm\fR is
decided as follows, specified in order of precedence:
.sp
.ne 2
.na
\fBap_id form (1)\fR
.ad
.sp .6
.RS 4n
if the \fIabsolute-slot-path\fR can fit within the fixed length limit of
\fBcfgadm\fR's \fIap_id\fR field, then \fIabsolute-slot-path\fR itself is used
.RE

.sp
.ne 2
.na
\fBap_id form (2)\fR
.ad
.sp .6
.RS 4n
(\fIabsolute-slot-path\fR exceeds the \fIap_id\fR length limit) if the last
\fIslot_path\fR component is contained within an expansion chassis, and it
contains a \fIserialid#\fR, then the last \fIslot_path\fR component is used.
The requirement for a \fIserialid#\fR in this form is to ensure a globally
unique \fIap_id\fR.
.RE

.sp
.ne 2
.na
\fBap_id form (3)\fR
.ad
.sp .6
.RS 4n
(\fIabsolute-slot-path\fR exceeds the \fIap_id\fR length limit) the default
form, "slot-id form (3)", of the last \fIslot_path\fR component is used
.RE

.sp
.LP
Whichever final \fIap_id\fR name is used, the \fIabsolute-slot-path\fR is
stored in the Information ("info") field which can be displayed using the
\fB-s\fR or \fB-v\fR options. This information can be used to physically locate
any \fIap_id\fRs named using "ap_id form (2)" or "ap_id form (3)". The
\fIabsolute-slot-path\fR is transformed slightly when stored in the information
field, by the replacement of a colon (":") with forward slashes ("/") to more
closely denote a topological context. The \fIabsolute-slot-path\fR can include
\fIslot-path\fR components that are not hotpluggable above the leaf or
right-most \fIslot-path\fR component up to the onboard host slot.
.sp
.LP
See the EXAMPLES section for a list of hotpluggable examples.
.SH OPTIONS
The following options are supported:
.sp
.ne 2
.na
\fB\fB-c\fR \fIfunction\fR\fR
.ad
.sp .6
.RS 4n
The following \fIfunction\fRs are supported for PCI hot pluggable slots:
.sp
.ne 2
.na
\fBconfigure\fR
.ad
.sp .6
.RS 4n
Configure the PCI device in the slot to be used by Solaris.
.RE

.sp
.ne 2
.na
\fBconnect\fR
.ad
.sp .6
.RS 4n
Connect the slot to PCI bus.
.RE

.sp
.ne 2
.na
\fBdisconnect\fR
.ad
.sp .6
.RS 4n
Disconnect the slot from the PCI bus.
.RE

.sp
.ne 2
.na
\fBinsert\fR
.ad
.sp .6
.RS 4n
Not supported.
.RE

.sp
.ne 2
.na
\fBremove\fR
.ad
.sp .6
.RS 4n
Not supported.
.RE

.sp
.ne 2
.na
\fBunconfigure\fR
.ad
.sp .6
.RS 4n
Logically remove the PCI device's resources from the system.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.sp .6
.RS 4n
Not supported.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR \fIap_id\fR | \fIap_type\fR\fR
.ad
.sp .6
.RS 4n
Print out PCI hot plug specific help message.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR \fIlist\fR\fR
.ad
.sp .6
.RS 4n
List the values of PCI Hot Plug slots.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIhardware_options\fR\fR
.ad
.sp .6
.RS 4n
No hardware specific options are currently defined.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIlisting_options\fR\fR
.ad
.sp .6
.RS 4n
Same as the generic \fBcfgadm\fR(8).
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fIap_id\fR\fR
.ad
.sp .6
.RS 4n
This command is only supported on platforms which support testing capability on
the slot.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
Execute in verbose mode.
.sp
When the \fB-v\fR option is used with the \fB-l\fR option, the \fBcfgadm\fR
command outputs information about the attachment point. For attachment points
located in a PCI Express hierarhcy, the Information field will contain the
attachment point's absolute slot path location, including any hardware or
platform specific labeling information for each component in the slot path.
Each component in the slot path will be separated by a "/" (forward slash). See
the PCI Express ap_id naming section. For PCI Hot Plug attachment points not
located in a PCI Express hierarchy, the \fBInformation\fR field will be the
slot's system label, if any. This string will be obtained from the
\fBslot-name\fR property of the slot's bus node. The information in the Type
field is printed with or without the \fB-v\fR option. The occupant \fBType\fR
field will describe the contents of the slot. There are 2 possible values:
.sp
.ne 2
.na
\fBunknown\fR
.ad
.sp .6
.RS 4n
The slot is empty. If a card is in the slot, the card is not configured or
there is no driver for the device on the card.
.RE

.sp
.ne 2
.na
\fB\fIsubclass\fR/\fIboard\fR\fR
.ad
.sp .6
.RS 4n
The card in the slot is either a single-function or multi-function device.
.sp
\fIsubclass\fR is a string representing the subclass code of the device, for
example, SCSI, \fBethernet\fR, \fBpci-isa\fR, and so forth. If the card is a
multi-functional device, \fBMULT\fR will get printed instead.
.sp
\fIboard\fR is a string representing the board type of the device. For example,
hp is the string used for a PCI Hot Plug adapter, hs is used for a Hot Swap
Board, nhs for a Non\(emHot Swap cPCI Board, bhs for a Basic Hot Swap cPCI
Board, and fhs for a Full Hot Swap cPCI Board.
.sp
Most PCI cards with more than one device are not multi-function devices, but
are implemented as a PCI bridge with arbitrary devices behind them. In those
cases, the subclass displayed is that of the PCI bridge. Most commonly, the
bridges are \fBpci-pci,\fR a generic PCI to PCI bridge or \fBstpci\fR, a
semi-transparent PCI bridge.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-x\fR \fIhardware_function\fR\fR
.ad
.sp .6
.RS 4n
Perform hardware specific function. These hardware specific functions should
not normally change the state of a receptacle or occupant.
.sp
The following \fIhardware_functions\fR are supported:
.sp
.ne 2
.na
\fBenable_slot | disable_slot\fR
.ad
.sp .6
.RS 4n
Change the state of the slot and preserve the state of slot across reboot.
Preservation of state across reboot is only supported on select platforms.
.sp
\fBenable_slot\fR enables the addition of hardware to this slot for hot
plugging and at boot time.
.sp
\fBdisable_slot\fR disables the addition of hardware to this slot for hot
plugging and at boot time. When a slot is disabled its condition is shown as
unusable.
.RE

.sp
.ne 2
.na
\fBenable_autoconfig | disable_autoconfig\fR
.ad
.sp .6
.RS 4n
Change the ability to autoconfigure the occupant of the slot. Only platforms
that support auto configuration support this feature.
.sp
\fBenable_autoconfig\fR enables the ability to autoconfigure the slot.
.sp
\fBdiable_autoconfig\fR disables the ability to autoconfigure the slot.
.sp
Autoconfiguration is done through the attention button on the PCI Express
platforms and through the injector/ejector latch on the CompactPCI platforms.
When autoconfiguration is disabled, the attention button or latch mechanism
cannot be used to configure the occupant of the slot.
.RE

.sp
.ne 2
.na
\fBled=[\fIled_sub_arg\fR],mode=[\fImode_sub_arg\fR]\fR
.ad
.sp .6
.RS 4n
Without sub-arguments, print a list of the current LED settings. With
sub-arguments, set the mode of a specific LED for a slot.
.sp
Specify \fIled_sub_arg\fR as \fBfault\fR, \fBpower\fR, \fBattn\fR, or
\fBactive\fR.
.sp
Specify \fImode_sub_arg\fR as \fBon\fR, \fBoff\fR or \fBblink\fR.
.sp
For PCI Express, only the power and attn LEDs are valid and only the state of
the \fBattn\fR LED can be changed.
.sp
Changing the state of the LED does not change the state of the receptacle or
occupant. Normally, the LEDs are controlled by the hot plug controller, no user
intervention is necessary. Use this command for testing purposes.
.sp
\fBCaution:\fR Changing the state of the LED can misrepresent the state of
occupant or receptacle.
.sp
The following command prints the values of LEDs:
.sp
.in +2
.nf
example#  \fBcfgadm -x led pci0:hpc0_slot1\fR
Ap_Id             Led
pci0:hpc0_slot1   power=on,fault=off,active=off,attn=off
.fi
.in -2
.sp

The following command turns on the Fault LED:
.sp
.in +2
.nf
example# \fBcfgadm -x led=fault,mode=on pci0:hpc0_slot1\fR
.fi
.in -2
.sp

The following command turns off the Power LED:
.sp
.in +2
.nf
example# \fBcfgadm -x led=power,mode=off pci0:hpc0_slot0\fR
.fi
.in -2
.sp

The following command sets the \fBactive\fR LED to blink to indicate the
location of the slot:
.sp
.in +2
.nf
example# \fBcfgadm -x led=active,mode=on pci0:hpc0_slot3\fR
.fi
.in -2
.sp

.RE

.RE

.SH EXAMPLES
\fBExample 1 \fRPrinting out the Value of Each Slot
.sp
.LP
The following command prints out the values of each slot:

.sp
.in +2
.nf
example# \fBcfgadm -l\fR
Ap_Id            Type         Receptacle   Occupant       Condition
c0               scsi-bus     connected    configured     unknown
c1               scsi-bus     connected    unconfigured   unknown
c2               scsi-bus     connected    unconfigured   unknown
cpci_slot1       stpci/fhs    connected    configured     ok
cpci_slot2       unknown      empty        unconfigured   unknown
cpci_slot4       stpci/fhs    connected    configured     ok
cpci_slot5       stpci/fhs    connected    configured     ok
pcie7            etherne/hp   connected    configured     ok
pcie8            unknown      empty        unconfigured   unknown
pcie9            fibre/hp     connected    configured     ok
.fi
.in -2
.sp

.LP
\fBExample 2 \fRReplacing a Card
.sp
.LP
The following command lists all DR-capable attachment points:

.sp
.in +2
.nf
example# \fBcfgadm\fR


Type             Receptacle   Occupant     Condition
c0               scsi-bus     connected    configured     unknown
c1               scsi-bus     connected    unconfigured   unknown
c2               scsi-bus     connected    unconfigured   unknown
cpci_slot1       stpci/fhs    connected    configured     ok
cpci_slot2       unknown      empty        unconfigured   unknown
cpci_slot4       stpci/fhs    connected    configured     ok
cpci_slot5       stpci/fhs    connected    configured     ok
pcie7            etherne/hp   connected    configured     ok
pcie8            unknown      empty        unconfigured   unknown
pcie9            fibre/hp     connected    configured     ok
.fi
.in -2
.sp

.sp
.LP
The following command unconfigures and electrically disconnects the card:

.sp
.in +2
.nf
example# \fBcfgadm -c disconnect cpci_slot4\fR
.fi
.in -2
.sp

.sp
.LP
The change can be verified by entering the following command:

.sp
.in +2
.nf
example# \fBcfgadm cpci_slot4\fR


Ap_Id                   Type         Receptacle   Occupant     Condition
cpci_slot4              unknown      disconnected unconfigured unknown
.fi
.in -2
.sp

.sp
.LP
Now the card can be swapped. The following command electrically connects and
configures the card:

.sp
.in +2
.nf
example# \fBcfgadm -c configure cpci_slot4\fR
.fi
.in -2
.sp

.sp
.LP
The change can be verified by entering the following command:

.sp
.in +2
.nf
example# \fBcfgadm cpci_slot4\fR


Ap_Id                   Type         Receptacle   Occupant     Condition
cpci_slot4              stpcipci/fhs connected    configured   ok
.fi
.in -2
.sp

.LP
\fBExample 3 \fRInterpreting ApIds for devices in a PCI Express topology
.sp
.LP
The following command shows a listing for a topology with both PCI Express and
PCI attachment points in I/O expansion chassis connected to hotpluggable slots
at the host level:

.sp
.in +2
.nf
example# \fBcfgadm -s cols=ap_id:info\fR


Ap_Id                          Information
iou#0-pci#0                    Location: iou#0-pci#0
iou#0-pci#1                    Location: iou#0-pci#1
iou#0-pci#1:iob.pci3           Location: iou#0-pci#1/iob.pci3
iou#0-pci#1:iob.pci4           Location: iou#0-pci#1/iob.pci4
iou#0-pci#2                    Location: iou#0-pci#2
iou#0-pci#2:iob58071.pcie1     Location: iou#0-pci#2/iob58071.pcie1
iou#0-pci#2:iob58071.special   Location: iou#0-pci#2/iob58071.special
iou#0-pci#3                    Location: iou#0-pci#3
iou#0-pci#3:iobBADF.pcie1      Location: iou#0-pci#3/iobBADF.pcie1
iou#0-pci#3:iobBADF.pcie2      Location: iou#0-pci#3/iobBADF.pcie2
iou#0-pci#3:iobBADF.pcie3      Location: iou#0-pci#3/iobBADF.pcie3
iou#0-pci#3:iobBADF.pci1       Location: iou#0-pci#3/iobBADF.pci1
iou#0-pci#3:iobBADF.pci2       Location: iou#0-pci#3/iobBADF.pci2
.fi
.in -2
.sp

.sp
.LP
In this example, the "iou#0-pci#[0-3]" represents the top-most hotpluggable
slots in the system. Since the "iou#<n>-pci#<n>" form does not match any of the
forms stated in the grammar specification section described earlier, we can
infer that such a name for the base component in this hotplug topology is
derived from the platform through the "slot-names" property.

.sp
.ne 2
.na
\fBSlot iou#0-pci#0\fR
.ad
.sp .6
.RS 4n
this slot is empty or its occupant is unconfigured
.RE

.sp
.ne 2
.na
\fBSlot iou#0-pci#1\fR
.ad
.sp .6
.RS 4n
this slot contains an expansion chassis with two hotpluggable slots, "pci3" and
"pci4". "pci3" and "pci4" represent two PCI slots contained within that
expansion chassis with physical slot numbers 3 and 4 respectively. The
expansion chassis in this case does not have or exports a \fIserial-id\fR.
.RE

.sp
.ne 2
.na
\fBSlot iou#0-pci#2\fR
.ad
.sp .6
.RS 4n
this slot contains a third party expansion chassis with a hexadecimal
\fIserial-id\fR of 58071. Within that expansion chassis are two hotpluggable
slots, "pcie1" and "special". "pcie1" represents a PCI Express slot with
physical slot number 1. The slot "special" has a label which is derived from
the platform, hardware or firmware.
.RE

.sp
.ne 2
.na
\fBSlot iou#0-pci#3\fR
.ad
.sp .6
.RS 4n
this slot contains a Sun expansion chassis with an FRU identifier of "BADF".
This expansion chassis contains three PCI Express slots, "pcie1", "pcie2", and
"pcie3" with physical slot numbers 1, 2, and 3 respectively; and two PCI slots,
"pci1" and "pci2" with physical slot numbers 1 and 2, respectively.
.RE

.sp
.LP
The following command shows a listing for a topology with both PCI Express and
PCI attachment points in I/O expansion chassis connected hotpluggable and
non-hotpluggable host slots:

.sp
.in +2
.nf
example# \fBcfgadm -s cols=ap_id:info\fR


Ap_Id                          Information
Slot1                          Location: Slot1
Slot2:iob4ffa56.pcie1          Location: Slot2/iob4ffa56.pcie1
Slot2:iob4ffa56.pcie2          Location: Slot2/iob4ffa56.pcie2
Slot5:iob3901.pci1             Location: Slot2/iob3901.pci1
Slot5:iob3901.pci2             Location: Slot2/iob3901.pci2
.fi
.in -2
.sp

.sp
.LP
In this example, the host system only has one hotpluggable slot, "Slot1". We
can infer that "Slot2" and "Slot5" are not hotpluggable slots because they do
not appear as attachment points themselves in \fBcfgadm\fR. However, "Slot2"
and "Slot5" each contains a third party expansion chassis with hotpluggable
slots.

.sp
.LP
The following command shows a listing for a topology with attachment points
that are lacking in certain device properties:

.sp
.in +2
.nf
example# \fBcfgadm -s cols=ap_id:info\fR

Ap_Id                          Information
px_pci7.pcie0                  Location: px_pci7.pcie0
px_pci11.pcie0                 Location: px_pci11.pcie0
px_pci11.pcie0:iob.pcie1       Location: px_pci11.pcie0/iob.pcie1
px_pci11.pcie0:iob.pcie2       Location: px_pci11.pcie0/iob.pcie2
px_pci11.pcie0:iob.pcie3       Location: px_pci11.pcie0/iob.pcie3
.fi
.in -2
.sp

.sp
.LP
In this example, the host system contains two hotpluggable slots,
"px_pci7.pcie0" and "px_pci11.pcie0". In this case, it uses "slot-id form (3)"
( the default form) for the base \fIslot-path\fR component in the
\fIabsolute-slot-path\fR because the framework could not obtain enough
information to produce other more descriptive forms of higher precedence.

.sp
.LP
Interpreting right-to-left, attachment point "px_pci7.pcie0" represents a PCI
Express slot with PCI device number 0 (which does not imply a physical slot
number of the same), bound to nexus driver "px_pci", instance 7. Likewise,
attachment point "px_pci11.pcie0" represents a PCI Express slot with PCI device
number 0 bound to driver instance 11 of px_pci.

.sp
.LP
Under "px_pci11.pcie0" is a third party expansion chassis without a
\fIserial-id\fR and with three hotpluggable PCI Express slots.

.sp
.LP
The following command shows a listing for a topology with attachment point
paths exceeding the \fIApId\fR field length limit:

.sp
.in +2
.nf
example# \fBcfgadm -s cols=ap_id:info\fR

Ap_Id                          Information
pcie4                          Location: pcie4
pcie4:iobSUNW.pcie1            Location: pcie4/iobSUNW.pcie1
pcie4:iobSUNW.pcie2            Location: pcie4/iobSUNW.pcie2
iob8879c3f3.pci1
                   Location: pcie4/iobSUNW.pcie2/iob8879c3f3.pci1
iob8879c3f3.pci2
                   Location: pcie4/iobSUNW.pcie2/iob8879c3f3.pci2
iob8879c3f3.pci3
                   Location: pcie4/iobSUNW.pcie2/iob8879c3f3.pci3
.fi
.in -2
.sp

.sp
.LP
In this example, there is only one hotpluggable slot, "pcie4" in the host.
Connected under "pcie4" is a SUN expansion chassis with FRU identifier "SUNW".
Nested under PCI Express slot "pcie2" of that expansion chassis (ApId
pcie4:iobSUNW.pcie2) lies another expansion chassis with three hotpluggable PCI
slots.

.sp
.LP
Because the length of the \fIabsolute-slot-path\fR form of
"pcie4/iobSUNW.pcie2/iob8879c3f3.pci1...3" exceeds the \fIApId\fR field length
limit, and the leaf \fIslot-path\fR component is globally unique, "ap_id form
(2)" is used, where the leaf \fIslot-path\fR component in the
\fIabsolute-slot-path\fR is used as the final \fIApId\fR.

.sp
.LP
The following command shows a listing for a topology with attachment point
paths exceeding the \fIApId\fR field length limit and lacking enough
information to uniquely identify the leaf \fIslot-id\fR on its own (for
instance, missing the \fIserial-id\fR):

.sp
.in +2
.nf
example# \fBcfgadm -s cols=ap_id:info\fR


Ap_Id                          Information
pcie4                          Location: pcie4
pcie4:iob4567812345678.pcie3   Location: pcie4/iob4567812345678.pcie3
px_pci20.pcie0
                   Location: pcie4/iob4567812345678.pcie3/iob.pcie1
px_pci21.pcie0
                   Location: pcie4/iob4567812345678.pcie3/iob.pcie2
.fi
.in -2
.sp

.sp
.LP
In this example, there is only one hotpluggable slot, "pcie4" in the host.
Connected under "pcie4" is a third party expansion chassis with hexadecimal
\fIserial-id\fR 4567812345678. Nested under the PCI Express slot "pcie3" of
that expansion chassis (ApId pcie4:iob4567812345678.pcie3), lies another third
part expansion chassis without a \fIserial-id\fR and with two hotpluggable PCI
Express slots.

.sp
.LP
Because the length of the \fIabsolute-slot-path\fR form of
"pcie4/iob4567812345678.pcie3/iob.pcie1...2" exceeds the \fIApId\fR field
length limit, and the leaf \fIslot-path\fR component is not globally unique,
"ap_id form (3)" is used. "ap_id form (2)" is where \fIslot-id\fR form (3)
(default form) of the leaf \fIslot-path\fR component in the
\fIabsolute-slot-path\fR is used as the final \fIApId\fR.

.sp
.LP
The default form or "slot-id form (3)" of the leaf component
".../iob.pcie1"represents a PCI Express slot with device number 0, bound to
driver instance 20 of "px_pci". Likewise, the default form of the leaf
component ".../iob.pcie2" represents a PCI Express slot with device number 0,
bound to driver instance 21 of "px_pci"

.SH FILES
.ne 2
.na
\fB/usr/lib/cfgadm/pci.so.1\fR
.ad
.sp .6
.RS 4n
Hardware specific library for PCI hot plugging.
.RE

.SH SEE ALSO
.BR config_admin (3CFGADM),
.BR libcfgadm (3LIB),
.BR attributes (7),
.BR cfgadm (8)
.sp
.LP
\fI\fR