System Administration Commands cfgadmpci(1M)
NAME
cfgadmpci - PCI, CompactPCI, and PCI Express Hotplug
hardware specific commands for cfgadm
SYNOPSIS
/usr/sbin/cfgadm [-f] [-y -n] [-v]
[-o hardwareoptions] -c function apid [apid]
/usr/sbin/cfgadm [-f] [-y -n] [-v]
[-o hardwareoptions] -x hardwarefunction apid
[apid]
/usr/sbin/cfgadm [-v] [-s listingoptions]
[-o hardwareoptions] [-l [apid aptype]
/usr/sbin/cfgadm [-v] [-o harwareoptions] -t apid [apid]
/usr/sbin/cfgadm [-v] [-o hardwarefunction] -h
[apid aptype]
DESCRIPTION
The PCI hardware specific library, /usr/lib/cfgadm/pci.so.1,
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
cfgadm command (see cfgadm(1M)). Hot plug administrative
models between PCI, CompactPCI, and PCI Express remain the
same except where noted in this document.
For PCI Hot Plug, each hot plug slot on a specific PCI bus
is represented by an attachment point of that specific PCI
bus.
An attachment point consist of two parts: a receptacle and
an occupant. The receptacle under PCI hot plug is usually
referred to as the physical hot pluggable slot; and the
occupant is usually referred to as the PCI adapter card that
plugs into the slot.
Attachment points are named through apids. There are two
types of apids: logical and physical. The physical apid is
based on the physical pathname, that is,
/devices/pci@1/hpc0slot3, whereas the logical apid is a
shorter, and more user-friendly name. For PCI hot pluggable
SunOS 5.11 Last change: 13 Jun 2008 1
System Administration Commands cfgadmpci(1M)
slots, the logical apid is usually the corresponding hot
plug controller driver name plus the logical slot number,
that is, pci0:hpc0slot1; PCI nexus driver, with hot plug
controller driver named hpc and slot number 1. The aptype
for Hot plug PCI is pci.
Note that the aptype is not the same as the information in
the Type field.
See the for a detailed description of the hot plug pro-
cedure.
PCI Express apid naming
For attachment points located in a PCI Express hierarchy
(that is, the parent or an ancestor is a PCI Express dev-
ice), including attachment points which are not PCI Express
devices themselves, the following naming scheme is used:
Grammar:
APID : absolute-slot-path
absolute-slot-path : slot-path[:slot-path[:slotpath ...]
slot-path : [fru-id.]slot-id
where fru-id indicates the chassis FRU, if any,
containing the slot-id
fru-id : fru-type[serialid#]
where fru-type is "iob" for PCI Express expansion
chassis, followed by its serial number serialid#,
if available
slot-id: slot-name device-type physical-slot# \
nexus-driver-name nexus-driver-instance.\
device-type pci-device-number
where slot-name is a name assigned by the platform or
hardware itself; device-type is either "pcie"for PCI Express
devices or "pci" for PCI devices; nexus-driver-name is the
driver name for the device component; physical-slot# is the
hardware slot number; and pci-device-number is the PCI dev-
ice number in standard PCI nomenclature.
First, an absolute-slot-path is constructed that attempts to
describe the attachment point's topological location in more
physically identifiable terms for the user . This absolute-
SunOS 5.11 Last change: 13 Jun 2008 2
System Administration Commands cfgadmpci(1M)
slot-path consists of slot-path components each seperated by
a ":" (colon). The leaf or left-most slot-path component
describes the device of the attachment point itself while
its right adjacent slot-path component up to the right or
top-most slot-path component describes the parent up to the
root devices, respectively.
Each slot-path consists of a slot-id optionally preceded by
an fru-id, which indicates an expansion chassis containing
the device described by slot-id (detailed below). fru-id
consists of fru-type followed by an optional serialid#.
fru-type is "iob" for PCI Express expansion chassis types,
while serialid# is either a 64-bit hexadecimal number indi-
cating a raw serial number obtained from the expansion
chassis hardware, or a 4 upper-case ASCI character sequence
for Sun branded expansion chassis.
Each slot-id consists of one of three possible forms:
slot-id form (1)
slot-names
slot-id form (2)
device-type physical-slot#
slot-id form (3)
nexus-driver-name nexus-driver-instance. device-type
pci-device-number
The precedence of which form to select flows from the lowest
form number to the highest form number, or from top to bot-
towm as described above. If a form cannot be successfully
constructed, then the next numerically higher form is
attempted.
The slot-names in "slot-id form (1)" is taken from the
"slot-names" property of the corresponding node in the dev-
ice tree and is a name assigned by hardware or the platform.
This format is not predefined or established.
SunOS 5.11 Last change: 13 Jun 2008 3
System Administration Commands cfgadmpci(1M)
In "slot-id form (2)", device-type indicates the device type
of the component's slot, and is either "pcie" for PCI
Express or "pci" for PCI, while physical-slot#, take from
the "physical-slot#" property of its corresponding device
node, indicates the hardware slot number of the component.
"slot-id form (3)" is used when all other forms cannot suc-
cessfully be constructed, and is considered to be the
default form. nexus-driver-name is the component's driver
name; nexus-driver-instance is such driver's instance;
device-type is the same as described in form (2); pci-
device-type is the PCI device number as described and used
for device configuration cycles in standard PCI nomencla-
ture.
In summary of the slot-path component, expanding the
optional FRU component that may precede it, slot-path will
consist one of the following forms in order:
(1) [ iob[serialid#]. ] slot-names
(2) [ iob[serialid#]. ] devicetype physicalslot#
(2) [ iob[serialid#]. ]
nexus-driver-name nexus-driver-instance.
devicetype pci-device-number
Lastly, the final form of the actual apid name used in
cfgadm is decided as follows, specified in order of pre-
cedence:
apid form (1)
if the absolute-slot-path can fit within the fixed
length limit of cfgadm's apid field, then absolute-
slot-path itself is used
apid form (2)
(absolute-slot-path exceeds the apid length limit) if
the last slotpath component is contained within an
expansion chassis, and it contains a serialid#, then the
last slotpath component is used. The requirement for a
serialid# in this form is to ensure a globally unique
apid.
SunOS 5.11 Last change: 13 Jun 2008 4
System Administration Commands cfgadmpci(1M)
apid form (3)
(absolute-slot-path exceeds the apid length limit) the
default form, "slot-id form (3)", of the last slotpath
component is used
Whichever final apid name is used, the absolute-slot-path
is stored in the Information ("info") field which can be
displayed using the -s or -voptions. This information can be
used to physically locate any apids named using "apid form
(2)" or "apid form (3)". The absolute-slot-path is tran-
formed slightly when stored in the information field, by the
replacement of a colon (":") with forward slashes ("/") to
more closely denote a topological context. The absolute-
slot-path can include slot-path components that are not hot-
pluggable above the leaf or right-most slot-path component
up to the onboard host slot.
See the EXAMPLES section for a list of hotpluggable exam-
ples.
OPTIONS
The following options are supported:
-c function
The following functions are supported for PCI hot plugg-
able slots:
configure
Configure the PCI device in the slot to be used by
Solaris.
connect
Connect the slot to PCI bus.
disconnect
Disconnect the slot from the PCI bus.
insert
Not supported.
SunOS 5.11 Last change: 13 Jun 2008 5
System Administration Commands cfgadmpci(1M)
remove
Not supported.
unconfigure
Logically remove the PCI device's resources from the
system.
-f
Not supported.
-h apid aptype
Print out PCI hot plug specific help message.
-l list
List the values of PCI Hot Plug slots.
-o hardwareoptions
No hardware specific options are currently defined.
-s listingoptions
Same as the generic cfgadm(1M).
-t apid
This command is only supported on platforms which sup-
port testing capability on the slot.
-v
Execute in verbose mode.
When the -v option is used with the -l option, the
cfgadm 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,
SunOS 5.11 Last change: 13 Jun 2008 6
System Administration Commands cfgadmpci(1M)
including any hardware or platform specific labeling
information for each component in the slot path. Each
component in the slot path will be seperated by a "/"
(foward slash). See the PCI Express apid naming sec-
tion. For PCI Hot Plug attachment points not located in
a PCI Express hieararchy, the Information field will be
the slot's system label, if any. This string will be
obtained from the slot-name property of the slot's bus
node. The information in the Type field is printed with
or without the -v option. The occupant Type field will
describe the contents of the slot. There are 2 possible
values:
unknown
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.
subclass/board
The card in the slot is either a single-function or
multi-function device.
subclass is a string representing the subclass code
of the device, for example, SCSI, ethernet, pci-isa,
and so forth. If the card is a multi-functional dev-
ice, MULT will get printed instead.
board 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-Hot Swap cPCI Board, bhs for a Basic
Hot Swap cPCI Board, and fhs for a Full Hot Swap
cPCI Board.
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 pci-pci, a
generic PCI to PCI bridge or stpci, a semi-
transparent PCI bridge.
-x hardwarefunction
Perform hardware specific function. These hardware
specific functions should not normally change the state
of a receptacle or occupant.
SunOS 5.11 Last change: 13 Jun 2008 7
System Administration Commands cfgadmpci(1M)
The following hardwarefunctions are supported:
enableslot disableslot
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.
enableslot enables the addition of hardware to this
slot for hot plugging and at boot time.
disableslot 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.
enableautoconfig disableautoconfig
Change the ability to autoconfigure the occupant of
the slot. Only platforms that support auto confi-
guration support this feature.
enableautoconfig enables the ability to autoconfig-
ure the slot.
diableautoconfig disables the ability to autocon-
figure the slot.
Autoconfiguration is done through the attention but-
ton 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 config-
ure the occupant of the slot.
led=[ledsubarg],mode=[modesubarg]
Without sub-arguments, print a list of the current
LED settings. With sub-arguments, set the mode of a
specific LED for a slot.
Specify ledsubarg as fault, power, attn, or
active.
Specify modesubarg as on, off or blink.
For PCI Express, only the power and attn LEDs are
valid and only the state of the attn LED can be
changed.
Changing the state of the LED does not change the
SunOS 5.11 Last change: 13 Jun 2008 8
System Administration Commands cfgadmpci(1M)
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.
Caution: Changing the state of the LED can
misrepresent the state of occupant or recepta-
cle.
The following command prints the values of LEDs:
example# cfgadm -x led pci0:hpc0slot1
ApId Led
pci0:hpc0slot1 power=on,fault=off,active=off,attn=off
The following command turns on the Fault LED:
example# cfgadm -x led=fault,mode=on pci0:hpc0slot1
The following command turns off the Power LED:
example# cfgadm -x led=power,mode=off pci0:hpc0slot0
The following command sets the active LED to blink
to indicate the location of the slot:
example# cfgadm -x led=active,mode=on pci0:hpc0slot3
EXAMPLES
Example 1 Printing out the Value of Each Slot
The following command prints out the values of each slot:
example# cfgadm -l
ApId Type Receptacle Occupant Condition
c0 scsi-bus connected configured unknown
c1 scsi-bus connected unconfigured unknown
c2 scsi-bus connected unconfigured unknown
cpcislot1 stpci/fhs connected configured ok
cpcislot2 unknown empty unconfigured unknown
cpcislot4 stpci/fhs connected configured ok
cpcislot5 stpci/fhs connected configured ok
pcie7 etherne/hp connected configured ok
SunOS 5.11 Last change: 13 Jun 2008 9
System Administration Commands cfgadmpci(1M)
pcie8 unknown empty unconfigured unknown
pcie9 fibre/hp connected configured ok
Example 2 Replacing a Card
The following command lists all DR-capable attachment
points:
example# cfgadm
Type Receptacle Occupant Condition
c0 scsi-bus connected configured unknown
c1 scsi-bus connected unconfigured unknown
c2 scsi-bus connected unconfigured unknown
cpcislot1 stpci/fhs connected configured ok
cpcislot2 unknown empty unconfigured unknown
cpcislot4 stpci/fhs connected configured ok
cpcislot5 stpci/fhs connected configured ok
pcie7 etherne/hp connected configured ok
pcie8 unknown empty unconfigured unknown
pcie9 fibre/hp connected configured ok
The following command unconfigures and electrically discon-
nects the card:
example# cfgadm -c disconnect cpcislot4
The change can be verified by entering the following com-
mand:
example# cfgadm cpcislot4
ApId Type Receptacle Occupant Condition
cpcislot4 unknown disconnected unconfigured unknown
SunOS 5.11 Last change: 13 Jun 2008 10
System Administration Commands cfgadmpci(1M)
Now the card can be swapped. The following command electri-
cally connects and configures the card:
example# cfgadm -c configure cpcislot4
The change can be verifed by entering the following command:
example# cfgadm cpcislot4
ApId Type Receptacle Occupant Condition
cpcislot4 stpcipci/fhs connected configured ok
Example 3 Interpreting ApIds for devices in a PCI Express
topology
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:
example# cfgadm -s cols=apid:info
ApId 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
In this example, the "iou#0-pci#[0-3]" represents the top-
most hotpluggable slots in the system. Since the "iou#-
SunOS 5.11 Last change: 13 Jun 2008 11
System Administration Commands cfgadmpci(1M)
pci#" form does not match any of the forms stated in the
grammar specification section described earilier, we can
infer that such a name for the base component in this hot-
plug topology is derived from the platform through the
"slot-names" property.
Slot iou#0-pci#0
this slot is empty or its occupant is unconfigured
Slot iou#0-pci#1
this slot contains an expansion chassis with two hot-
pluggable 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 serial-id.
Slot iou#0-pci#2
this slot contains a third party expansion chassis with
a hexadecimal serial-id of 58071. Within that expansion
chassis are two hotpluggable slots, "pcie1" and "spe-
cial". "pcie1" represents a PCI Express slot with physi-
cal slot number 1. The slot "special" has a label which
is derived from the platform, hardware or firmware.
Slot iou#0-pci#3
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.
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:
example# cfgadm -s cols=apid:info
SunOS 5.11 Last change: 13 Jun 2008 12
System Administration Commands cfgadmpci(1M)
ApId 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
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 cfgadm. However, "Slot2" and "Slot5"
each contains a third party expansion chassis with hotplugg-
able slots.
The following command shows a listing for a topology with
attachment points that are lacking in certain device proper-
ties:
example# cfgadm -s cols=apid:info
ApId Information
pxpci7.pcie0 Location: pxpci7.pcie0
pxpci11.pcie0 Location: pxpci11.pcie0
pxpci11.pcie0:iob.pcie1 Location: pxpci11.pcie0/iob.pcie1
pxpci11.pcie0:iob.pcie2 Location: pxpci11.pcie0/iob.pcie2
pxpci11.pcie0:iob.pcie3 Location: pxpci11.pcie0/iob.pcie3
In this example, the host system contains two hotpluggable
slots, "pxpci7.pcie0" and "pxpci11.pcie0". In this case,
it uses "slot-id form (3)" ( the default form) for the base
slot-path component in the absolute-slot-path because the
framework could not obtain enough information to produce
other more descriptive forms of higher precedence.
Interpreting right-to-left, attachment point "pxpci7.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 "pxpci", instance 7. Likewise,
attachment point "pxpci11.pcie0" represents a PCI Express
slot with PCI device number 0 bound to driver instance 11 of
pxpci.
SunOS 5.11 Last change: 13 Jun 2008 13
System Administration Commands cfgadmpci(1M)
Under "pxpci11.pcie0" is a third party expansion chassis
without a serial-id and with three hotpluggable PCI Express
slots.
The following command shows a listing for a topology with
attachment point paths exceeding the ApId field length
limit:
example# cfgadm -s cols=apid:info
ApId 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
In this example, there is only one hotpluggable slot,
"pcie4" in the host. Connected under "pcie4" is a SUN expan-
sion 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.
Because the length of the absolute-slot-path form of
"pcie4/iobSUNW.pcie2/iob8879c3f3.pci1...3" exceeds the ApId
field length limit, and the leaf slot-path component is glo-
bally unique, "apid form (2)" is used, where the leaf
slot-path component in the absolute-slot-path is used as the
final ApId.
The following command shows a listing for a topology with
attachment point paths exceeding the ApId field length limit
and lacking enough information to uniquely identify the leaf
slot-id on its own (for instance, missing the serial-id):
example# cfgadm -s cols=apid:info
SunOS 5.11 Last change: 13 Jun 2008 14
System Administration Commands cfgadmpci(1M)
ApId Information
pcie4 Location: pcie4
pcie4:iob4567812345678.pcie3 Location: pcie4/iob4567812345678.pcie3
pxpci20.pcie0
Location: pcie4/iob4567812345678.pcie3/iob.pcie1
pxpci21.pcie0
Location: pcie4/iob4567812345678.pcie3/iob.pcie2
In this example, there is only one hotpluggable slot,
"pcie4" in the host. Connected under "pcie4" is a third
party expansion chassis with hexadecimal serial-id
4567812345678. Nested under the PCI Express slot "pcie3" of
that expansion chassis (ApId pcie4:iob4567812345678.pcie3),
lies another third part expansion chassis without a serial-
id and with two hotpluggable PCI Express slots.
Because the length of the absolute-slot-path form of
"pcie4/iob4567812345678.pcie3/iob.pcie1...2" exceeds the
ApId field length limit, and the leaf slot-path component is
not globally unique, "apid form (3)" is used. "apid form
(2)" is where slot-id form (3) (default form) of the leaf
slot-path component in the absolute-slot-path is used as the
final ApId.
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 "pxpci". 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 "pxpci"
FILES
/usr/lib/cfgadm/pci.so.1
Hardware specific library for PCI hot plugging.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 13 Jun 2008 15
System Administration Commands cfgadmpci(1M)
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsl
SEE ALSO
cfgadm(1M), configadmin(3CFGADM), libcfgadm(3LIB), attri-
butes(5)
SunOS 5.11 Last change: 13 Jun 2008 16
|
