CFGADM_PCI(8) Maintenance Commands and Procedures CFGADM_PCI(8)

NAME

cfgadm_pci - PCI, CompactPCI, and PCI Express Hotplug hardware
specific commands for cfgadm

SYNOPSIS

/usr/sbin/cfgadm [-f] [-y | -n] [-v]
[-o hardware_options] -c function ap_id [ap_id]


/usr/sbin/cfgadm [-f] [-y | -n] [-v]
[-o hardware_options] -x hardware_function ap_id
[ap_id]


/usr/sbin/cfgadm [-v] [-s listing_options]
[-o hardware_options] [-l [ap_id | ap_type]]


/usr/sbin/cfgadm [-v] [-o hardware_options] -t ap_id [ap_id]


/usr/sbin/cfgadm [-v] [-o hardware_function] -h
[ap_id| ap_type]

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(8)). 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 ap_ids. There are two types of
ap_ids: logical and physical. The physical ap_id is based on the
physical pathname, that is, /devices/pci@1/hpc0_slot3, whereas the
logical ap_id is a shorter, and more user-friendly name. For PCI hot
pluggable slots, the logical ap_id 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 ap_type for Hot plug PCI is pci.


Note that the ap_type is not the same as the information in the Type
field.


See the for a detailed description of the hot plug procedure.

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:

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 device 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-slot-path consists of
slot-path components each separated 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 indicating a raw serial number obtained from the
expansion chassis hardware, or a 4 upper-case ASCII 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 bottom 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 device tree and is a name
assigned by hardware or the platform. This format is not predefined
or established.


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 successfully
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 nomenclature.


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#]. ] device_type physical_slot#
(2) [ iob[serialid#]. ]
nexus-driver-name nexus-driver-instance.
device_type pci-device-number


Lastly, the final form of the actual ap_id name used in cfgadm is
decided as follows, specified in order of precedence:

ap_id form (1)

if the absolute-slot-path can fit within the fixed length limit
of cfgadm's ap_id field, then absolute-slot-path itself is used


ap_id form (2)

(absolute-slot-path exceeds the ap_id length limit) if the last
slot_path component is contained within an expansion chassis, and
it contains a serialid#, then the last slot_path component is
used. The requirement for a serialid# in this form is to ensure
a globally unique ap_id.


ap_id form (3)

(absolute-slot-path exceeds the ap_id length limit) the default
form, "slot-id form (3)", of the last slot_path component is used


Whichever final ap_id name is used, the absolute-slot-path is stored
in the Information ("info") field which can be displayed using the -s
or -v options. This information can be used to physically locate any
ap_ids named using "ap_id form (2)" or "ap_id form (3)". The
absolute-slot-path 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
absolute-slot-path can include slot-path components that are not
hotpluggable above the leaf or right-most slot-path component up to
the onboard host slot.


See the EXAMPLES section for a list of hotpluggable examples.

OPTIONS

The following options are supported:

-c function

The following functions are supported for PCI hot pluggable
slots:

configure

Configure the PCI device in the slot to be used.


connect

Connect the slot to the PCI bus.


disconnect

Disconnect the slot from the PCI bus.


insert

Not supported.


remove

Not supported.


unconfigure

Logically remove the PCI device's resources from the system.


-f

Not supported.


-h ap_id | ap_type

Print out PCI hot plug specific help message.


-l list

List the values of PCI Hot Plug slots.


-o hardware_options

No hardware specific options are currently defined.


-s listing_options

Same as the generic cfgadm(8).


-t ap_id

This command is only supported on platforms which support 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 hierarchy, 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 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 device, 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 hardware_function

Perform hardware specific function. These hardware specific
functions should not normally change the state of a receptacle or
occupant.

The following hardware_functions are supported:

enable_slot | disable_slot

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.

enable_slot enables the addition of hardware to this slot for
hot plugging and at boot time.

disable_slot 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.


enable_autoconfig | disable_autoconfig

Change the ability to autoconfigure the occupant of the slot.
Only platforms that support auto configuration support this
feature.

enable_autoconfig enables the ability to autoconfigure the
slot.

disable_autoconfig disables the ability to autoconfigure the
slot.

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.


led=[led_sub_arg],mode=[mode_sub_arg]

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 led_sub_arg as fault, power, attn, or active.

Specify mode_sub_arg 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 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 receptacle.

The following command prints the values of LEDs:

example# cfgadm -x led pci0:hpc0_slot1
Ap_Id Led
pci0:hpc0_slot1 power=on,fault=off,active=off,attn=off


The following command turns on the Fault LED:

example# cfgadm -x led=fault,mode=on pci0:hpc0_slot1


The following command turns off the Power LED:

example# cfgadm -x led=power,mode=off pci0:hpc0_slot0


The following command sets the active LED to blink to
indicate the location of the slot:

example# cfgadm -x led=active,mode=on pci0:hpc0_slot3

EXAMPLES

Example 1: Printing out the Value of Each Slot

The following command prints out the values of each slot:


example# cfgadm -l
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

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
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


The following command unconfigures and electrically disconnects the
card:


example# cfgadm -c disconnect cpci_slot4


The change can be verified by entering the following command:


example# cfgadm cpci_slot4


Ap_Id Type Receptacle Occupant Condition
cpci_slot4 unknown disconnected unconfigured unknown


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


example# cfgadm -c configure cpci_slot4


The change can be verified by entering the following command:


example# cfgadm cpci_slot4


Ap_Id Type Receptacle Occupant Condition
cpci_slot4 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=ap_id:info


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


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.


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 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 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 "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.


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=ap_id:info


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


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 hotpluggable slots.


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


example# cfgadm -s cols=ap_id:info

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


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 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 "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.


Under "px_pci11.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=ap_id:info

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


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.


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 globally unique,
"ap_id 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=ap_id:info


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


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, "ap_id form (3)" is used. "ap_id 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 "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"

FILES

/usr/lib/cfgadm/pci.so.1

Hardware specific library for PCI hot plugging.

SEE ALSO

config_admin(3CFGADM), libcfgadm(3LIB), attributes(7), cfgadm(8)

August 2, 2023 CFGADM_PCI(8)