1cfgadm_pci(1M) System Administration Commands cfgadm_pci(1M)
2
6 cfgadm_pci - PCI, CompactPCI, and PCI Express Hotplug hardware specific
7 commands for cfgadm
8
10 /usr/sbin/cfgadm [-f] [-y | -n] [-v]
11 [-o hardware_options] -c function ap_id [ap_id]
12 /usr/sbin/cfgadm [-f] [-y | -n] [-v]
15 [-o hardware_options] -x hardware_function ap_id
16 [ap_id]
17 /usr/sbin/cfgadm [-v] [-s listing_options]
20 [-o hardware_options] [-l [ap_id | ap_type]]
21 /usr/sbin/cfgadm [-v] [-o harware_options] -t ap_id [ap_id]
24 /usr/sbin/cfgadm [-v] [-o hardware_function] -h
27 [ap_id| ap_type]
28
31 The PCI hardware specific library, /usr/lib/cfgadm/pci.so.1, provides
32 the support for hot plugging PCI, CompactPCI, and PCI Express adapter
33 cards into the respective hot pluggable slots in a system that is hot
34 plug capable, through the cfgadm command (see cfgadm(1M)). Hot plug
35 administrative models between PCI, CompactPCI, and PCI Express remain
36 the same except where noted in this document.
37 For PCI Hot Plug, each hot plug slot on a specific PCI bus is repre‐
40 sented by an attachment point of that specific PCI bus.
41 An attachment point consist of two parts: a receptacle and an occupant.
44 The receptacle under PCI hot plug is usually referred to as the physi‐
45 cal hot pluggable slot; and the occupant is usually referred to as the
46 PCI adapter card that plugs into the slot.
47 Attachment points are named through ap_ids. There are two types of
50 ap_ids: logical and physical. The physical ap_id is based on the physi‐
51 cal pathname, that is, /devices/pci@1/hpc0_slot3, whereas the logical
52 ap_id is a shorter, and more user-friendly name. For PCI hot pluggable
53 slots, the logical ap_id is usually the corresponding hot plug con‐
54 troller driver name plus the logical slot number, that is,
55 pci0:hpc0slot1; PCI nexus driver, with hot plug controller driver named
56 hpc and slot number 1. The ap_type for Hot plug PCI is pci.
57 Note that the ap_type is not the same as the information in the Type
60 field.
61 See the for a detailed description of the hot plug procedure.
64 PCI Express ap_id naming
66 For attachment points located in a PCI Express hierarchy (that is, the
67 parent or an ancestor is a PCI Express device), including attachment
68 points which are not PCI Express devices themselves, the following nam‐
69 ing scheme is used:
70 Grammar:
72 APID : absolute-slot-path
73 absolute-slot-path : slot-path[:slot-path[:slotpath ...]]
75 slot-path : [fru-id.]slot-id
77 where fru-id indicates the chassis FRU, if any,
78 containing the slot-id
79 fru-id : fru-type[serialid#]
81 where fru-type is "iob" for PCI Express expansion
82 chassis, followed by its serial number serialid#,
83 if available
84 slot-id: slot-name | device-type physical-slot# |\
86 nexus-driver-name nexus-driver-instance.\
87 device-type pci-device-number
88 where slot-name is a name assigned by the platform or hardware itself;
93 device-type is either "pcie"for PCI Express devices or "pci" for PCI
94 devices; nexus-driver-name is the driver name for the device component;
95 physical-slot# is the hardware slot number; and pci-device-number is
96 the PCI device number in standard PCI nomenclature.
97 First, an absolute-slot-path is constructed that attempts to describe
100 the attachment point's topological location in more physically identi‐
101 fiable terms for the user . This absolute-slot-path consists of slot-
102 path components each seperated by a ":" (colon). The leaf or left-most
103 slot-path component describes the device of the attachment point itself
104 while its right adjacent slot-path component up to the right or top-
105 most slot-path component describes the parent up to the root devices,
106 respectively.
107 Each slot-path consists of a slot-id optionally preceded by an fru-id,
110 which indicates an expansion chassis containing the device described by
111 slot-id (detailed below). fru-id consists of fru-type followed by an
112 optional serialid#. fru-type is "iob" for PCI Express expansion chassis
113 types, while serialid# is either a 64-bit hexadecimal number indicating
114 a raw serial number obtained from the expansion chassis hardware, or a
115 4 upper-case ASCII character sequence for Sun branded expansion chas‐
116 sis.
117 Each slot-id consists of one of three possible forms:
120 slot-id form (1)
122 slot-names
124 slot-id form (2)
127 device-type physical-slot#
129 slot-id form (3)
132 nexus-driver-name nexus-driver-instance. device-type pci-device-
134 number
135 The precedence of which form to select flows from the lowest form num‐
139 ber to the highest form number, or from top to bottowm as described
140 above. If a form cannot be successfully constructed, then the next
141 numerically higher form is attempted.
142 The slot-names in "slot-id form (1)" is taken from the "slot-names"
145 property of the corresponding node in the device tree and is a name
146 assigned by hardware or the platform. This format is not predefined or
147 established.
148 In "slot-id form (2)", device-type indicates the device type of the
151 component's slot, and is either "pcie" for PCI Express or "pci" for
152 PCI, while physical-slot#, take from the "physical-slot#" property of
153 its corresponding device node, indicates the hardware slot number of
154 the component.
155 "slot-id form (3)" is used when all other forms cannot successfully be
158 constructed, and is considered to be the default form. nexus-driver-
159 name is the component's driver name; nexus-driver-instance is such
160 driver's instance; device-type is the same as described in form (2);
161 pci-device-type is the PCI device number as described and used for
162 device configuration cycles in standard PCI nomenclature.
163 In summary of the slot-path component, expanding the optional FRU com‐
166 ponent that may precede it, slot-path will consist one of the following
167 forms in order:
168 (1) [ iob[serialid#]. ] slot-names
170 (2) [ iob[serialid#]. ] device_type physical_slot#
171 (2) [ iob[serialid#]. ]
172 nexus-driver-name nexus-driver-instance.
173 device_type pci-device-number
174 Lastly, the final form of the actual ap_id name used in cfgadm is
179 decided as follows, specified in order of precedence:
180 ap_id form (1)
182 if the absolute-slot-path can fit within the fixed length limit of
184 cfgadm's ap_id field, then absolute-slot-path itself is used
185 ap_id form (2)
188 (absolute-slot-path exceeds the ap_id length limit) if the last
190 slot_path component is contained within an expansion chassis, and
191 it contains a serialid#, then the last slot_path component is used.
192 The requirement for a serialid# in this form is to ensure a glob‐
193 ally unique ap_id.
194 ap_id form (3)
197 (absolute-slot-path exceeds the ap_id length limit) the default
199 form, "slot-id form (3)", of the last slot_path component is used
200 Whichever final ap_id name is used, the absolute-slot-path is stored in
204 the Information ("info") field which can be displayed using the -s or
205 -voptions. This information can be used to physically locate any ap_ids
206 named using "ap_id form (2)" or "ap_id form (3)". The absolute-slot-
207 path is tranformed slightly when stored in the information field, by
208 the replacement of a colon (":") with forward slashes ("/") to more
209 closely denote a topological context. The absolute-slot-path can
210 include slot-path components that are not hotpluggable above the leaf
211 or right-most slot-path component up to the onboard host slot.
212 See the EXAMPLES section for a list of hotpluggable examples.
215
217 The following options are supported:
218 -c function
220 The following functions are supported for PCI hot pluggable slots:
222 configure
224 Configure the PCI device in the slot to be used by Solaris.
226 connect
229 Connect the slot to PCI bus.
231 disconnect
234 Disconnect the slot from the PCI bus.
236 insert
239 Not supported.
241 remove
244 Not supported.
246 unconfigure
249 Logically remove the PCI device's resources from the system.
251 -f
255 Not supported.
257 -h ap_id | ap_type
260 Print out PCI hot plug specific help message.
262 -l list
265 List the values of PCI Hot Plug slots.
267 -o hardware_options
270 No hardware specific options are currently defined.
272 -s listing_options
275 Same as the generic cfgadm(1M).
277 -t ap_id
280 This command is only supported on platforms which support testing
282 capability on the slot.
283 -v
286 Execute in verbose mode.
288 When the -v option is used with the -l option, the cfgadm command
290 outputs information about the attachment point. For attachment
291 points located in a PCI Express hierarhcy, the Information field
292 will contain the attachment point's absolute slot path location,
293 including any hardware or platform specific labeling information
294 for each component in the slot path. Each component in the slot
295 path will be seperated by a "/" (foward slash). See the PCI Express
296 ap_id naming section. For PCI Hot Plug attachment points not
297 located in a PCI Express hieararchy, the Information field will be
298 the slot's system label, if any. This string will be obtained from
299 the slot-name property of the slot's bus node. The information in
300 the Type field is printed with or without the -v option. The occu‐
301 pant Type field will describe the contents of the slot. There are 2
302 possible values:
303 unknown
305 The slot is empty. If a card is in the slot, the card is not
307 configured or there is no driver for the device on the card.
308 subclass/board
311 The card in the slot is either a single-function or multi-func‐
313 tion device.
314 subclass is a string representing the subclass code of the
316 device, for example, SCSI, ethernet, pci-isa, and so forth. If
317 the card is a multi-functional device, MULT will get printed
318 instead.
319 board is a string representing the board type of the device.
321 For example, hp is the string used for a PCI Hot Plug adapter,
322 hs is used for a Hot Swap Board, nhs for a Non—Hot Swap cPCI
323 Board, bhs for a Basic Hot Swap cPCI Board, and fhs for a Full
324 Hot Swap cPCI Board.
325 Most PCI cards with more than one device are not multi-function
327 devices, but are implemented as a PCI bridge with arbitrary
328 devices behind them. In those cases, the subclass displayed is
329 that of the PCI bridge. Most commonly, the bridges are pci-pci,
330 a generic PCI to PCI bridge or stpci, a semi-transparent PCI
331 bridge.
332 -x hardware_function
336 Perform hardware specific function. These hardware specific func‐
338 tions should not normally change the state of a receptacle or occu‐
339 pant.
340 The following hardware_functions are supported:
342 enable_slot | disable_slot
344 Change the state of the slot and preserve the state of slot
346 across reboot. Preservation of state across reboot is only sup‐
347 ported on select platforms.
348 enable_slot enables the addition of hardware to this slot for
350 hot plugging and at boot time.
351 disable_slot disables the addition of hardware to this slot for
353 hot plugging and at boot time. When a slot is disabled its con‐
354 dition is shown as unusable.
355 enable_autoconfig | disable_autoconfig
358 Change the ability to autoconfigure the occupant of the slot.
360 Only platforms that support auto configuration support this
361 feature.
362 enable_autoconfig enables the ability to autoconfigure the
364 slot.
365 diable_autoconfig disables the ability to autoconfigure the
367 slot.
368 Autoconfiguration is done through the attention button on the
370 PCI Express platforms and through the injector/ejector latch on
371 the CompactPCI platforms. When autoconfiguration is disabled,
372 the attention button or latch mechanism cannot be used to con‐
373 figure the occupant of the slot.
374 led=[led_sub_arg],mode=[mode_sub_arg]
377 Without sub-arguments, print a list of the current LED set‐
379 tings. With sub-arguments, set the mode of a specific LED for a
380 slot.
381 Specify led_sub_arg as fault, power, attn, or active.
383 Specify mode_sub_arg as on, off or blink.
385 For PCI Express, only the power and attn LEDs are valid and
387 only the state of the attn LED can be changed.
388 Changing the state of the LED does not change the state of the
390 receptacle or occupant. Normally, the LEDs are controlled by
391 the hot plug controller, no user intervention is necessary. Use
392 this command for testing purposes.
393 Caution: Changing the state of the LED can misrepresent
395 the state of occupant or receptacle.
396 The following command prints the values of LEDs:
398 example# cfgadm -x led pci0:hpc0_slot1
400 Ap_Id Led
401 pci0:hpc0_slot1 power=on,fault=off,active=off,attn=off
402 The following command turns on the Fault LED:
405 example# cfgadm -x led=fault,mode=on pci0:hpc0_slot1
407 The following command turns off the Power LED:
410 example# cfgadm -x led=power,mode=off pci0:hpc0_slot0
412 The following command sets the active LED to blink to indicate
415 the location of the slot:
416 example# cfgadm -x led=active,mode=on pci0:hpc0_slot3
418
424 Example 1 Printing out the Value of Each Slot
425 The following command prints out the values of each slot:
428 example# cfgadm -l
431 Ap_Id Type Receptacle Occupant Condition
432 c0 scsi-bus connected configured unknown
433 c1 scsi-bus connected unconfigured unknown
434 c2 scsi-bus connected unconfigured unknown
435 cpci_slot1 stpci/fhs connected configured ok
436 cpci_slot2 unknown empty unconfigured unknown
437 cpci_slot4 stpci/fhs connected configured ok
438 cpci_slot5 stpci/fhs connected configured ok
439 pcie7 etherne/hp connected configured ok
440 pcie8 unknown empty unconfigured unknown
441 pcie9 fibre/hp connected configured ok
442 Example 2 Replacing a Card
446 The following command lists all DR-capable attachment points:
449 example# cfgadm
452 Type Receptacle Occupant Condition
455 c0 scsi-bus connected configured unknown
456 c1 scsi-bus connected unconfigured unknown
457 c2 scsi-bus connected unconfigured unknown
458 cpci_slot1 stpci/fhs connected configured ok
459 cpci_slot2 unknown empty unconfigured unknown
460 cpci_slot4 stpci/fhs connected configured ok
461 cpci_slot5 stpci/fhs connected configured ok
462 pcie7 etherne/hp connected configured ok
463 pcie8 unknown empty unconfigured unknown
464 pcie9 fibre/hp connected configured ok
465 The following command unconfigures and electrically disconnects the
470 card:
471 example# cfgadm -c disconnect cpci_slot4
474 The change can be verified by entering the following command:
479 example# cfgadm cpci_slot4
482 Ap_Id Type Receptacle Occupant Condition
485 cpci_slot4 unknown disconnected unconfigured unknown
486 Now the card can be swapped. The following command electrically con‐
491 nects and configures the card:
492 example# cfgadm -c configure cpci_slot4
495 The change can be verifed by entering the following command:
500 example# cfgadm cpci_slot4
503 Ap_Id Type Receptacle Occupant Condition
506 cpci_slot4 stpcipci/fhs connected configured ok
507 Example 3 Interpreting ApIds for devices in a PCI Express topology
511 The following command shows a listing for a topology with both PCI
514 Express and PCI attachment points in I/O expansion chassis connected to
515 hotpluggable slots at the host level:
516 example# cfgadm -s cols=ap_id:info
519 Ap_Id Information
522 iou#0-pci#0 Location: iou#0-pci#0
523 iou#0-pci#1 Location: iou#0-pci#1
524 iou#0-pci#1:iob.pci3 Location: iou#0-pci#1/iob.pci3
525 iou#0-pci#1:iob.pci4 Location: iou#0-pci#1/iob.pci4
526 iou#0-pci#2 Location: iou#0-pci#2
527 iou#0-pci#2:iob58071.pcie1 Location: iou#0-pci#2/iob58071.pcie1
528 iou#0-pci#2:iob58071.special Location: iou#0-pci#2/iob58071.special
529 iou#0-pci#3 Location: iou#0-pci#3
530 iou#0-pci#3:iobBADF.pcie1 Location: iou#0-pci#3/iobBADF.pcie1
531 iou#0-pci#3:iobBADF.pcie2 Location: iou#0-pci#3/iobBADF.pcie2
532 iou#0-pci#3:iobBADF.pcie3 Location: iou#0-pci#3/iobBADF.pcie3
533 iou#0-pci#3:iobBADF.pci1 Location: iou#0-pci#3/iobBADF.pci1
534 iou#0-pci#3:iobBADF.pci2 Location: iou#0-pci#3/iobBADF.pci2
535 In this example, the "iou#0-pci#[0-3]" represents the top-most hotplug‐
540 gable slots in the system. Since the "iou#<n>-pci#<n>" form does not
541 match any of the forms stated in the grammar specification section
542 described earilier, we can infer that such a name for the base compo‐
543 nent in this hotplug topology is derived from the platform through the
544 "slot-names" property.
545 Slot iou#0-pci#0
548 this slot is empty or its occupant is unconfigured
550 Slot iou#0-pci#1
553 this slot contains an expansion chassis with two hotpluggable
555 slots, "pci3" and "pci4". "pci3" and "pci4" represent two PCI slots
556 contained within that expansion chassis with physical slot numbers
557 3 and 4 respectively. The expansion chassis in this case does not
558 have or exports a serial-id.
559 Slot iou#0-pci#2
562 this slot contains a third party expansion chassis with a hexadeci‐
564 mal serial-id of 58071. Within that expansion chassis are two hot‐
565 pluggable slots, "pcie1" and "special". "pcie1" represents a PCI
566 Express slot with physical slot number 1. The slot "special" has a
567 label which is derived from the platform, hardware or firmware.
568 Slot iou#0-pci#3
571 this slot contains a Sun expansion chassis with an FRU identifier
573 of "BADF". This expansion chassis contains three PCI Express slots,
574 "pcie1", "pcie2", and "pcie3" with physical slot numbers 1, 2, and
575 3 respectively; and two PCI slots, "pci1" and "pci2" with physical
576 slot numbers 1 and 2, respectively.
577 The following command shows a listing for a topology with both PCI
581 Express and PCI attachment points in I/O expansion chassis connected
582 hotpluggable and non-hotpluggable host slots:
583 example# cfgadm -s cols=ap_id:info
586 Ap_Id Information
589 Slot1 Location: Slot1
590 Slot2:iob4ffa56.pcie1 Location: Slot2/iob4ffa56.pcie1
591 Slot2:iob4ffa56.pcie2 Location: Slot2/iob4ffa56.pcie2
592 Slot5:iob3901.pci1 Location: Slot2/iob3901.pci1
593 Slot5:iob3901.pci2 Location: Slot2/iob3901.pci2
594 In this example, the host system only has one hotpluggable slot,
599 "Slot1". We can infer that "Slot2" and "Slot5" are not hotpluggable
600 slots because they do not appear as attachment points themselves in
601 cfgadm. However, "Slot2" and "Slot5" each contains a third party expan‐
602 sion chassis with hotpluggable slots.
603 The following command shows a listing for a topology with attachment
607 points that are lacking in certain device properties:
608 example# cfgadm -s cols=ap_id:info
611 Ap_Id Information
613 px_pci7.pcie0 Location: px_pci7.pcie0
614 px_pci11.pcie0 Location: px_pci11.pcie0
615 px_pci11.pcie0:iob.pcie1 Location: px_pci11.pcie0/iob.pcie1
616 px_pci11.pcie0:iob.pcie2 Location: px_pci11.pcie0/iob.pcie2
617 px_pci11.pcie0:iob.pcie3 Location: px_pci11.pcie0/iob.pcie3
618 In this example, the host system contains two hotpluggable slots,
623 "px_pci7.pcie0" and "px_pci11.pcie0". In this case, it uses "slot-id
624 form (3)" ( the default form) for the base slot-path component in the
625 absolute-slot-path because the framework could not obtain enough infor‐
626 mation to produce other more descriptive forms of higher precedence.
627 Interpreting right-to-left, attachment point "px_pci7.pcie0" represents
631 a PCI Express slot with PCI device number 0 (which does not imply a
632 physical slot number of the same), bound to nexus driver "px_pci",
633 instance 7. Likewise, attachment point "px_pci11.pcie0" represents a
634 PCI Express slot with PCI device number 0 bound to driver instance 11
635 of px_pci.
636 Under "px_pci11.pcie0" is a third party expansion chassis without a
640 serial-id and with three hotpluggable PCI Express slots.
641 The following command shows a listing for a topology with attachment
645 point paths exceeding the ApId field length limit:
646 example# cfgadm -s cols=ap_id:info
649 Ap_Id Information
651 pcie4 Location: pcie4
652 pcie4:iobSUNW.pcie1 Location: pcie4/iobSUNW.pcie1
653 pcie4:iobSUNW.pcie2 Location: pcie4/iobSUNW.pcie2
654 iob8879c3f3.pci1
655 Location: pcie4/iobSUNW.pcie2/iob8879c3f3.pci1
656 iob8879c3f3.pci2
657 Location: pcie4/iobSUNW.pcie2/iob8879c3f3.pci2
658 iob8879c3f3.pci3
659 Location: pcie4/iobSUNW.pcie2/iob8879c3f3.pci3
660 In this example, there is only one hotpluggable slot, "pcie4" in the
665 host. Connected under "pcie4" is a SUN expansion chassis with FRU iden‐
666 tifier "SUNW". Nested under PCI Express slot "pcie2" of that expansion
667 chassis (ApId pcie4:iobSUNW.pcie2) lies another expansion chassis with
668 three hotpluggable PCI slots.
669 Because the length of the absolute-slot-path form of "pcie4/iob‐
673 SUNW.pcie2/iob8879c3f3.pci1...3" exceeds the ApId field length limit,
674 and the leaf slot-path component is globally unique, "ap_id form (2)"
675 is used, where the leaf slot-path component in the absolute-slot-path
676 is used as the final ApId.
677 The following command shows a listing for a topology with attachment
681 point paths exceeding the ApId field length limit and lacking enough
682 information to uniquely identify the leaf slot-id on its own (for
683 instance, missing the serial-id):
684 example# cfgadm -s cols=ap_id:info
687 Ap_Id Information
690 pcie4 Location: pcie4
691 pcie4:iob4567812345678.pcie3 Location: pcie4/iob4567812345678.pcie3
692 px_pci20.pcie0
693 Location: pcie4/iob4567812345678.pcie3/iob.pcie1
694 px_pci21.pcie0
695 Location: pcie4/iob4567812345678.pcie3/iob.pcie2
696 In this example, there is only one hotpluggable slot, "pcie4" in the
701 host. Connected under "pcie4" is a third party expansion chassis with
702 hexadecimal serial-id 4567812345678. Nested under the PCI Express slot
703 "pcie3" of that expansion chassis (ApId pcie4:iob4567812345678.pcie3),
704 lies another third part expansion chassis without a serial-id and with
705 two hotpluggable PCI Express slots.
706 Because the length of the absolute-slot-path form of
710 "pcie4/iob4567812345678.pcie3/iob.pcie1...2" exceeds the ApId field
711 length limit, and the leaf slot-path component is not globally unique,
712 "ap_id form (3)" is used. "ap_id form (2)" is where slot-id form (3)
713 (default form) of the leaf slot-path component in the absolute-slot-
714 path is used as the final ApId.
715 The default form or "slot-id form (3)" of the leaf component
719 ".../iob.pcie1"represents a PCI Express slot with device number 0,
720 bound to driver instance 20 of "px_pci". Likewise, the default form of
721 the leaf component ".../iob.pcie2" represents a PCI Express slot with
722 device number 0, bound to driver instance 21 of "px_pci"
723
726 /usr/lib/cfgadm/pci.so.1
727 Hardware specific library for PCI hot plugging.
729
732 See attributes(5) for descriptions of the following attributes:
733 ┌─────────────────────────────┬─────────────────────────────┐
738 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
739 ├─────────────────────────────┼─────────────────────────────┤
740 │Availability │SUNWcsl │
741 └─────────────────────────────┴─────────────────────────────┘
742
744 cfgadm(1M), config_admin(3CFGADM), libcfgadm(3LIB), attributes(5)
745SunOS 5.11 13 Jun 2008 cfgadm_pci(1M)