| CFGADM_PCI(8) | Maintenance Commands and Procedures | CFGADM_PCI(8) |
cfgadm_pci - PCI, CompactPCI, and PCI Express Hotplug hardware specific commands for cfgadm
/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]
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.
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-id form (2)
slot-id form (3)
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)
ap_id form (2)
ap_id form (3)
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.
The following options are supported:
-c function
configure
connect
disconnect
insert
remove
unconfigure
-f
-h ap_id | ap_type
-l list
-o hardware_options
-s listing_options
-t ap_id
-v
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
subclass/board
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
The following hardware_functions are supported:
enable_slot | disable_slot
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
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]
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
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
Slot iou#0-pci#1
Slot iou#0-pci#2
Slot iou#0-pci#3
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"
/usr/lib/cfgadm/pci.so.1
config_admin(3CFGADM), libcfgadm(3LIB), attributes(7), cfgadm(8)
| August 2, 2023 | OmniOS |