| blob | 875b7e7a0ba75d76492562313e291a37bd146f4a |
1 '\" te
2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH CFGADM_PCI 1M "Jun 13, 2008"
7 .SH NAME
8 cfgadm_pci \- PCI, CompactPCI, and PCI Express Hotplug hardware specific
9 commands for cfgadm
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR]
14 [\fB-o\fR \fIhardware_options\fR] \fB-c\fR \fIfunction\fR \fIap_id\fR [\fIap_id\fR]
15 .fi
17 .LP
18 .nf
19 \fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR]
20 [\fB-o\fR \fIhardware_options\fR] \fB-x\fR \fIhardware_function\fR \fIap_id\fR
21 [\fIap_id\fR]
22 .fi
24 .LP
25 .nf
26 \fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-s\fR \fIlisting_options\fR]
27 [\fB-o\fR \fIhardware_options\fR] [\fB-l\fR [\fIap_id\fR | \fIap_type\fR]]
28 .fi
30 .LP
31 .nf
32 \fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-o\fR \fIharware_options\fR] \fB-t\fR \fIap_id\fR [\fIap_id\fR]
33 .fi
35 .LP
36 .nf
37 \fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-o\fR \fIhardware_function\fR] \fB-h\fR
38 [\fIap_id\fR| \fIap_type\fR]
39 .fi
41 .SH DESCRIPTION
42 .sp
43 .LP
44 The PCI hardware specific library, \fB/usr/lib/cfgadm/pci.so.1\fR, provides the
45 support for hot plugging PCI, CompactPCI, and PCI Express adapter cards into
46 the respective hot pluggable slots in a system that is hot plug capable,
47 through the \fBcfgadm\fR command (see \fBcfgadm\fR(1M)). Hot plug
48 administrative models between PCI, CompactPCI, and PCI Express remain the same
49 except where noted in this document.
50 .sp
51 .LP
52 For PCI Hot Plug, each hot plug slot on a specific PCI bus is represented by an
53 attachment point of that specific PCI bus.
54 .sp
55 .LP
56 An attachment point consist of two parts: a receptacle and an occupant. The
57 \fBreceptacle\fR under PCI hot plug is usually referred to as the physical hot
58 pluggable slot; and the \fBoccupant\fR is usually referred to as the PCI
59 adapter card that plugs into the slot.
60 .sp
61 .LP
62 Attachment points are named through \fBap_id\fRs. There are two types of
63 \fBap_id\fRs: logical and physical. The physical \fBap_id\fR is based on the
64 physical pathname, that is, \fB/devices/pci@1/hpc0_slot3\fR, whereas the
65 logical \fBap_id\fR is a shorter, and more user-friendly name. For PCI hot
66 pluggable slots, the logical \fBap_id\fR is usually the corresponding hot plug
67 controller driver name plus the logical slot number, that is,
68 \fBpci0:hpc0slot1\fR; PCI nexus driver, with hot plug controller driver named
69 \fBhpc\fR and slot number \fB1\fR. The \fBap_type\fR for Hot plug PCI is
70 \fBpci\fR.
71 .sp
72 .LP
73 Note that the \fBap_type\fR is not the same as the information in the
74 \fBType\fR field.
75 .sp
76 .LP
77 See the \fI\fR for a detailed description of the hot plug procedure.
78 .SS "PCI Express ap_id naming"
79 .sp
80 .LP
81 For attachment points located in a PCI Express hierarchy (that is, the parent
82 or an ancestor is a PCI Express device), including attachment points which are
83 not PCI Express devices themselves, the following naming scheme is used:
84 .sp
85 .in +2
86 .nf
87 Grammar:
88 APID : absolute-slot-path
90 absolute-slot-path : \fIslot-path\fR[\fI:slot-path\fR[\fI:slotpath\fR ...]]
92 slot-path : [\fIfru-id\fR.]\fIslot-id\fR
93 where \fIfru-id\fR indicates the chassis FRU, if any,
94 containing the \fIslot-id\fR
96 fru-id : \fIfru-type\fR[\fIserialid#\fR]
97 where \fIfru-type\fR is "iob" for PCI Express expansion
98 chassis, followed by its serial number \fIserialid#\fR,
99 if available
101 slot-id: \fIslot-name\fR | \fIdevice-type\fR \fIphysical-slot#\fR |\e
102 \fInexus-driver-name\fR \fInexus-driver-instance\fR.\e
103 \fIdevice-type\fR \fIpci-device-number\fR
104 .fi
105 .in -2
106 .sp
108 .sp
109 .LP
110 where \fIslot-name\fR is a name assigned by the platform or hardware itself;
111 \fIdevice-type\fR is either "pcie"for PCI Express devices or "pci" for PCI
112 devices; \fInexus-driver-name\fR is the driver name for the device component;
113 \fIphysical-slot#\fR is the hardware slot number; and \fIpci-device-number\fR
114 is the PCI device number in standard PCI nomenclature.
115 .sp
116 .LP
117 First, an \fIabsolute-slot-path\fR is constructed that attempts to describe the
118 attachment point's topological location in more physically identifiable terms
119 for the user . This \fIabsolute-slot-path\fR consists of \fIslot-path\fR
120 components each seperated by a ":" (colon). The leaf or left-most
121 \fIslot-path\fR component describes the device of the attachment point itself
122 while its right adjacent \fIslot-path\fR component up to the right or top-most
123 \fIslot-path\fR component describes the parent up to the root devices,
124 respectively.
125 .sp
126 .LP
127 Each \fIslot-path\fR consists of a \fIslot-id\fR optionally preceded by an
128 \fIfru-id\fR, which indicates an expansion chassis containing the device
129 described by \fIslot-id\fR (detailed below). \fIfru-id\fR consists of
130 \fIfru-type\fR followed by an optional \fIserialid#\fR. \fIfru-type\fR is "iob"
131 for PCI Express expansion chassis types, while \fIserialid#\fR is either a
132 64-bit hexadecimal number indicating a raw serial number obtained from the
133 expansion chassis hardware, or a 4 upper-case ASCII character sequence for Sun
134 branded expansion chassis.
135 .sp
136 .LP
137 Each \fIslot-id\fR consists of one of three possible forms:
138 .sp
139 .ne 2
140 .na
141 \fBslot-id form (1)\fR
142 .ad
143 .sp .6
144 .RS 4n
145 \fIslot-names\fR
146 .RE
148 .sp
149 .ne 2
150 .na
151 \fBslot-id form (2)\fR
152 .ad
153 .sp .6
154 .RS 4n
155 \fIdevice-type\fR \fIphysical-slot#\fR
156 .RE
158 .sp
159 .ne 2
160 .na
161 \fBslot-id form (3)\fR
162 .ad
163 .sp .6
164 .RS 4n
165 \fInexus-driver-name\fR \fInexus-driver-instance\fR. \fIdevice-type\fR
166 \fIpci-device-number\fR
167 .RE
169 .sp
170 .LP
171 The precedence of which form to select flows from the lowest form number to the
172 highest form number, or from top to bottowm as described above. If a form
173 cannot be successfully constructed, then the next numerically higher form is
174 attempted.
175 .sp
176 .LP
177 The \fIslot-names\fR in "slot-id form (1)" is taken from the "slot-names"
178 property of the corresponding node in the device tree and is a name assigned by
179 hardware or the platform. This format is not predefined or established.
180 .sp
181 .LP
182 In "slot-id form (2)", \fIdevice-type\fR indicates the device type of the
183 component's slot, and is either "pcie" for PCI Express or "pci" for PCI, while
184 \fIphysical-slot#\fR, take from the "physical-slot#" property of its
185 corresponding device node, indicates the hardware slot number of the component.
186 .sp
187 .LP
188 "slot-id form (3)" is used when all other forms cannot successfully be
189 constructed, and is considered to be the default form. \fInexus-driver-name\fR
190 is the component's driver name; \fInexus-driver-instance\fR is such driver's
191 instance; \fIdevice-type\fR is the same as described in form (2);
192 \fIpci-device-type\fR is the PCI device number as described and used for device
193 configuration cycles in standard PCI nomenclature.
194 .sp
195 .LP
196 In summary of the \fIslot-path\fR component, expanding the optional FRU
197 component that may precede it, \fIslot-path\fR will consist one of the
198 following forms in order:
199 .sp
200 .in +2
201 .nf
202 (1) [ iob[serialid#]. ] slot-names
203 (2) [ iob[serialid#]. ] device_type physical_slot#
204 (2) [ iob[serialid#]. ]
205 nexus-driver-name nexus-driver-instance.
206 device_type pci-device-number
207 .fi
208 .in -2
209 .sp
211 .sp
212 .LP
213 Lastly, the final form of the actual \fIap_id\fR name used in \fBcfgadm\fR is
214 decided as follows, specified in order of precedence:
215 .sp
216 .ne 2
217 .na
218 \fBap_id form (1)\fR
219 .ad
220 .sp .6
221 .RS 4n
222 if the \fIabsolute-slot-path\fR can fit within the fixed length limit of
223 \fBcfgadm\fR's \fIap_id\fR field, then \fIabsolute-slot-path\fR itself is used
224 .RE
226 .sp
227 .ne 2
228 .na
229 \fBap_id form (2)\fR
230 .ad
231 .sp .6
232 .RS 4n
233 (\fIabsolute-slot-path\fR exceeds the \fIap_id\fR length limit) if the last
234 \fIslot_path\fR component is contained within an expansion chassis, and it
235 contains a \fIserialid#\fR, then the last \fIslot_path\fR component is used.
236 The requirement for a \fIserialid#\fR in this form is to ensure a globally
237 unique \fIap_id\fR.
238 .RE
240 .sp
241 .ne 2
242 .na
243 \fBap_id form (3)\fR
244 .ad
245 .sp .6
246 .RS 4n
247 (\fIabsolute-slot-path\fR exceeds the \fIap_id\fR length limit) the default
248 form, "slot-id form (3)", of the last \fIslot_path\fR component is used
249 .RE
251 .sp
252 .LP
253 Whichever final \fIap_id\fR name is used, the \fIabsolute-slot-path\fR is
254 stored in the Information ("info") field which can be displayed using the
255 \fB-s\fR or \fB-v\fRoptions. This information can be used to physically locate
256 any \fIap_id\fRs named using "ap_id form (2)" or "ap_id form (3)". The
257 \fIabsolute-slot-path\fR is tranformed slightly when stored in the information
258 field, by the replacement of a colon (":") with forward slashes ("/") to more
259 closely denote a topological context. The \fIabsolute-slot-path\fR can include
260 \fIslot-path\fR components that are not hotpluggable above the leaf or
261 right-most \fIslot-path\fR component up to the onboard host slot.
262 .sp
263 .LP
264 See the EXAMPLES section for a list of hotpluggable examples.
265 .SH OPTIONS
266 .sp
267 .LP
268 The following options are supported:
269 .sp
270 .ne 2
271 .na
272 \fB\fB-c\fR \fIfunction\fR\fR
273 .ad
274 .sp .6
275 .RS 4n
276 The following \fIfunction\fRs are supported for PCI hot pluggable slots:
277 .sp
278 .ne 2
279 .na
280 \fBconfigure\fR
281 .ad
282 .sp .6
283 .RS 4n
284 Configure the PCI device in the slot to be used by Solaris.
285 .RE
287 .sp
288 .ne 2
289 .na
290 \fBconnect\fR
291 .ad
292 .sp .6
293 .RS 4n
294 Connect the slot to PCI bus.
295 .RE
297 .sp
298 .ne 2
299 .na
300 \fBdisconnect\fR
301 .ad
302 .sp .6
303 .RS 4n
304 Disconnect the slot from the PCI bus.
305 .RE
307 .sp
308 .ne 2
309 .na
310 \fBinsert\fR
311 .ad
312 .sp .6
313 .RS 4n
314 Not supported.
315 .RE
317 .sp
318 .ne 2
319 .na
320 \fBremove\fR
321 .ad
322 .sp .6
323 .RS 4n
324 Not supported.
325 .RE
327 .sp
328 .ne 2
329 .na
330 \fBunconfigure\fR
331 .ad
332 .sp .6
333 .RS 4n
334 Logically remove the PCI device's resources from the system.
335 .RE
337 .RE
339 .sp
340 .ne 2
341 .na
342 \fB\fB-f\fR\fR
343 .ad
344 .sp .6
345 .RS 4n
346 Not supported.
347 .RE
349 .sp
350 .ne 2
351 .na
352 \fB\fB-h\fR \fIap_id\fR | \fIap_type\fR\fR
353 .ad
354 .sp .6
355 .RS 4n
356 Print out PCI hot plug specific help message.
357 .RE
359 .sp
360 .ne 2
361 .na
362 \fB\fB-l\fR \fIlist\fR\fR
363 .ad
364 .sp .6
365 .RS 4n
366 List the values of PCI Hot Plug slots.
367 .RE
369 .sp
370 .ne 2
371 .na
372 \fB\fB-o\fR \fIhardware_options\fR\fR
373 .ad
374 .sp .6
375 .RS 4n
376 No hardware specific options are currently defined.
377 .RE
379 .sp
380 .ne 2
381 .na
382 \fB\fB-s\fR \fIlisting_options\fR\fR
383 .ad
384 .sp .6
385 .RS 4n
386 Same as the generic \fBcfgadm\fR(1M).
387 .RE
389 .sp
390 .ne 2
391 .na
392 \fB\fB-t\fR \fIap_id\fR\fR
393 .ad
394 .sp .6
395 .RS 4n
396 This command is only supported on platforms which support testing capability on
397 the slot.
398 .RE
400 .sp
401 .ne 2
402 .na
403 \fB\fB-v\fR\fR
404 .ad
405 .sp .6
406 .RS 4n
407 Execute in verbose mode.
408 .sp
409 When the \fB-v\fR option is used with the \fB-l\fR option, the \fBcfgadm\fR
410 command outputs information about the attachment point. For attachment points
411 located in a PCI Express hierarhcy, the Information field will contain the
412 attachment point's absolute slot path location, including any hardware or
413 platform specific labeling information for each component in the slot path.
414 Each component in the slot path will be seperated by a "/" (foward slash). See
415 the PCI Express ap_id naming section. For PCI Hot Plug attachment points not
416 located in a PCI Express hieararchy, the \fBInformation\fR field will be the
417 slot's system label, if any. This string will be obtained from the
418 \fBslot-name\fR property of the slot's bus node. The information in the Type
419 field is printed with or without the \fB-v\fR option. The occupant \fBType\fR
420 field will describe the contents of the slot. There are 2 possible values:
421 .sp
422 .ne 2
423 .na
424 \fBunknown\fR
425 .ad
426 .sp .6
427 .RS 4n
428 The slot is empty. If a card is in the slot, the card is not configured or
429 there is no driver for the device on the card.
430 .RE
432 .sp
433 .ne 2
434 .na
435 \fB\fIsubclass\fR/\fIboard\fR\fR
436 .ad
437 .sp .6
438 .RS 4n
439 The card in the slot is either a single-function or multi-function device.
440 .sp
441 \fIsubclass\fR is a string representing the subclass code of the device, for
442 example, SCSI, \fBethernet\fR, \fBpci-isa\fR, and so forth. If the card is a
443 multi-functional device, \fBMULT\fR will get printed instead.
444 .sp
445 \fIboard\fR is a string representing the board type of the device. For example,
446 hp is the string used for a PCI Hot Plug adapter, hs is used for a Hot Swap
447 Board, nhs for a Non\(emHot Swap cPCI Board, bhs for a Basic Hot Swap cPCI
448 Board, and fhs for a Full Hot Swap cPCI Board.
449 .sp
450 Most PCI cards with more than one device are not multi-function devices, but
451 are implemented as a PCI bridge with arbitrary devices behind them. In those
452 cases, the subclass displayed is that of the PCI bridge. Most commonly, the
453 bridges are \fBpci-pci,\fR a generic PCI to PCI bridge or \fBstpci\fR, a
454 semi-transparent PCI bridge.
455 .RE
457 .RE
459 .sp
460 .ne 2
461 .na
462 \fB\fB-x\fR \fIhardware_function\fR\fR
463 .ad
464 .sp .6
465 .RS 4n
466 Perform hardware specific function. These hardware specific functions should
467 not normally change the state of a receptacle or occupant.
468 .sp
469 The following \fIhardware_functions\fR are supported:
470 .sp
471 .ne 2
472 .na
473 \fBenable_slot | disable_slot\fR
474 .ad
475 .sp .6
476 .RS 4n
477 Change the state of the slot and preserve the state of slot across reboot.
478 Preservation of state across reboot is only supported on select platforms.
479 .sp
480 \fBenable_slot\fR enables the addition of hardware to this slot for hot
481 plugging and at boot time.
482 .sp
483 \fBdisable_slot\fR disables the addition of hardware to this slot for hot
484 plugging and at boot time. When a slot is disabled its condition is shown as
485 unusable.
486 .RE
488 .sp
489 .ne 2
490 .na
491 \fBenable_autoconfig | disable_autoconfig\fR
492 .ad
493 .sp .6
494 .RS 4n
495 Change the ability to autoconfigure the occupant of the slot. Only platforms
496 that support auto configuration support this feature.
497 .sp
498 \fBenable_autoconfig\fR enables the ability to autoconfigure the slot.
499 .sp
500 \fBdiable_autoconfig\fR disables the ability to autoconfigure the slot.
501 .sp
502 Autoconfiguration is done through the attention button on the PCI Express
503 platforms and through the injector/ejector latch on the CompactPCI platforms.
504 When autoconfiguration is disabled, the attention button or latch mechanism
505 cannot be used to configure the occupant of the slot.
506 .RE
508 .sp
509 .ne 2
510 .na
511 \fBled=[\fIled_sub_arg\fR],mode=[\fImode_sub_arg\fR]\fR
512 .ad
513 .sp .6
514 .RS 4n
515 Without sub-arguments, print a list of the current LED settings. With
516 sub-arguments, set the mode of a specific LED for a slot.
517 .sp
518 Specify \fIled_sub_arg\fR as \fBfault\fR, \fBpower\fR, \fBattn\fR, or
519 \fBactive\fR.
520 .sp
521 Specify \fImode_sub_arg\fR as \fBon\fR, \fBoff\fR or \fBblink\fR.
522 .sp
523 For PCI Express, only the power and attn LEDs are valid and only the state of
524 the \fBattn\fR LED can be changed.
525 .sp
526 Changing the state of the LED does not change the state of the receptacle or
527 occupant. Normally, the LEDs are controlled by the hot plug controller, no user
528 intervention is necessary. Use this command for testing purposes.
529 .sp
530 \fBCaution:\fR Changing the state of the LED can misrepresent the state of
531 occupant or receptacle.
532 .sp
533 The following command prints the values of LEDs:
534 .sp
535 .in +2
536 .nf
537 example# \fBcfgadm -x led pci0:hpc0_slot1\fR
538 Ap_Id Led
539 pci0:hpc0_slot1 power=on,fault=off,active=off,attn=off
540 .fi
541 .in -2
542 .sp
544 The following command turns on the Fault LED:
545 .sp
546 .in +2
547 .nf
548 example# \fBcfgadm -x led=fault,mode=on pci0:hpc0_slot1\fR
549 .fi
550 .in -2
551 .sp
553 The following command turns off the Power LED:
554 .sp
555 .in +2
556 .nf
557 example# \fBcfgadm -x led=power,mode=off pci0:hpc0_slot0\fR
558 .fi
559 .in -2
560 .sp
562 The following command sets the \fBactive\fR LED to blink to indicate the
563 location of the slot:
564 .sp
565 .in +2
566 .nf
567 example# \fBcfgadm -x led=active,mode=on pci0:hpc0_slot3\fR
568 .fi
569 .in -2
570 .sp
572 .RE
574 .RE
576 .SH EXAMPLES
577 .LP
578 \fBExample 1 \fRPrinting out the Value of Each Slot
579 .sp
580 .LP
581 The following command prints out the values of each slot:
583 .sp
584 .in +2
585 .nf
586 example# \fBcfgadm -l\fR
587 Ap_Id Type Receptacle Occupant Condition
588 c0 scsi-bus connected configured unknown
589 c1 scsi-bus connected unconfigured unknown
590 c2 scsi-bus connected unconfigured unknown
591 cpci_slot1 stpci/fhs connected configured ok
592 cpci_slot2 unknown empty unconfigured unknown
593 cpci_slot4 stpci/fhs connected configured ok
594 cpci_slot5 stpci/fhs connected configured ok
595 pcie7 etherne/hp connected configured ok
596 pcie8 unknown empty unconfigured unknown
597 pcie9 fibre/hp connected configured ok
598 .fi
599 .in -2
600 .sp
602 .LP
603 \fBExample 2 \fRReplacing a Card
604 .sp
605 .LP
606 The following command lists all DR-capable attachment points:
608 .sp
609 .in +2
610 .nf
611 example# \fBcfgadm\fR
614 Type Receptacle Occupant Condition
615 c0 scsi-bus connected configured unknown
616 c1 scsi-bus connected unconfigured unknown
617 c2 scsi-bus connected unconfigured unknown
618 cpci_slot1 stpci/fhs connected configured ok
619 cpci_slot2 unknown empty unconfigured unknown
620 cpci_slot4 stpci/fhs connected configured ok
621 cpci_slot5 stpci/fhs connected configured ok
622 pcie7 etherne/hp connected configured ok
623 pcie8 unknown empty unconfigured unknown
624 pcie9 fibre/hp connected configured ok
625 .fi
626 .in -2
627 .sp
629 .sp
630 .LP
631 The following command unconfigures and electrically disconnects the card:
633 .sp
634 .in +2
635 .nf
636 example# \fBcfgadm -c disconnect cpci_slot4\fR
637 .fi
638 .in -2
639 .sp
641 .sp
642 .LP
643 The change can be verified by entering the following command:
645 .sp
646 .in +2
647 .nf
648 example# \fBcfgadm cpci_slot4\fR
651 Ap_Id Type Receptacle Occupant Condition
652 cpci_slot4 unknown disconnected unconfigured unknown
653 .fi
654 .in -2
655 .sp
657 .sp
658 .LP
659 Now the card can be swapped. The following command electrically connects and
660 configures the card:
662 .sp
663 .in +2
664 .nf
665 example# \fBcfgadm -c configure cpci_slot4\fR
666 .fi
667 .in -2
668 .sp
670 .sp
671 .LP
672 The change can be verifed by entering the following command:
674 .sp
675 .in +2
676 .nf
677 example# \fBcfgadm cpci_slot4\fR
680 Ap_Id Type Receptacle Occupant Condition
681 cpci_slot4 stpcipci/fhs connected configured ok
682 .fi
683 .in -2
684 .sp
686 .LP
687 \fBExample 3 \fRInterpreting ApIds for devices in a PCI Express topology
688 .sp
689 .LP
690 The following command shows a listing for a topology with both PCI Express and
691 PCI attachment points in I/O expansion chassis connected to hotpluggable slots
692 at the host level:
694 .sp
695 .in +2
696 .nf
697 example# \fBcfgadm -s cols=ap_id:info\fR
700 Ap_Id Information
701 iou#0-pci#0 Location: iou#0-pci#0
702 iou#0-pci#1 Location: iou#0-pci#1
703 iou#0-pci#1:iob.pci3 Location: iou#0-pci#1/iob.pci3
704 iou#0-pci#1:iob.pci4 Location: iou#0-pci#1/iob.pci4
705 iou#0-pci#2 Location: iou#0-pci#2
706 iou#0-pci#2:iob58071.pcie1 Location: iou#0-pci#2/iob58071.pcie1
707 iou#0-pci#2:iob58071.special Location: iou#0-pci#2/iob58071.special
708 iou#0-pci#3 Location: iou#0-pci#3
709 iou#0-pci#3:iobBADF.pcie1 Location: iou#0-pci#3/iobBADF.pcie1
710 iou#0-pci#3:iobBADF.pcie2 Location: iou#0-pci#3/iobBADF.pcie2
711 iou#0-pci#3:iobBADF.pcie3 Location: iou#0-pci#3/iobBADF.pcie3
712 iou#0-pci#3:iobBADF.pci1 Location: iou#0-pci#3/iobBADF.pci1
713 iou#0-pci#3:iobBADF.pci2 Location: iou#0-pci#3/iobBADF.pci2
714 .fi
715 .in -2
716 .sp
718 .sp
719 .LP
720 In this example, the "iou#0-pci#[0-3]" represents the top-most hotpluggable
721 slots in the system. Since the "iou#<n>-pci#<n>" form does not match any of the
722 forms stated in the grammar specification section described earilier, we can
723 infer that such a name for the base component in this hotplug topology is
724 derived from the platform through the "slot-names" property.
726 .sp
727 .ne 2
728 .na
729 \fBSlot iou#0-pci#0\fR
730 .ad
731 .sp .6
732 .RS 4n
733 this slot is empty or its occupant is unconfigured
734 .RE
736 .sp
737 .ne 2
738 .na
739 \fBSlot iou#0-pci#1\fR
740 .ad
741 .sp .6
742 .RS 4n
743 this slot contains an expansion chassis with two hotpluggable slots, "pci3" and
744 "pci4". "pci3" and "pci4" represent two PCI slots contained within that
745 expansion chassis with physical slot numbers 3 and 4 respectively. The
746 expansion chassis in this case does not have or exports a \fIserial-id\fR.
747 .RE
749 .sp
750 .ne 2
751 .na
752 \fBSlot iou#0-pci#2\fR
753 .ad
754 .sp .6
755 .RS 4n
756 this slot contains a third party expansion chassis with a hexadecimal
757 \fIserial-id\fR of 58071. Within that expansion chassis are two hotpluggable
758 slots, "pcie1" and "special". "pcie1" represents a PCI Express slot with
759 physical slot number 1. The slot "special" has a label which is derived from
760 the platform, hardware or firmware.
761 .RE
763 .sp
764 .ne 2
765 .na
766 \fBSlot iou#0-pci#3\fR
767 .ad
768 .sp .6
769 .RS 4n
770 this slot contains a Sun expansion chassis with an FRU identifier of "BADF".
771 This expansion chassis contains three PCI Express slots, "pcie1", "pcie2", and
772 "pcie3" with physical slot numbers 1, 2, and 3 respectively; and two PCI slots,
773 "pci1" and "pci2" with physical slot numbers 1 and 2, respectively.
774 .RE
776 .sp
777 .LP
778 The following command shows a listing for a topology with both PCI Express and
779 PCI attachment points in I/O expansion chassis connected hotpluggable and
780 non-hotpluggable host slots:
782 .sp
783 .in +2
784 .nf
785 example# \fBcfgadm -s cols=ap_id:info\fR
788 Ap_Id Information
789 Slot1 Location: Slot1
790 Slot2:iob4ffa56.pcie1 Location: Slot2/iob4ffa56.pcie1
791 Slot2:iob4ffa56.pcie2 Location: Slot2/iob4ffa56.pcie2
792 Slot5:iob3901.pci1 Location: Slot2/iob3901.pci1
793 Slot5:iob3901.pci2 Location: Slot2/iob3901.pci2
794 .fi
795 .in -2
796 .sp
798 .sp
799 .LP
800 In this example, the host system only has one hotpluggable slot, "Slot1". We
801 can infer that "Slot2" and "Slot5" are not hotpluggable slots because they do
802 not appear as attachment points themselves in \fBcfgadm\fR. However, "Slot2"
803 and "Slot5" each contains a third party expansion chassis with hotpluggable
804 slots.
806 .sp
807 .LP
808 The following command shows a listing for a topology with attachment points
809 that are lacking in certain device properties:
811 .sp
812 .in +2
813 .nf
814 example# \fBcfgadm -s cols=ap_id:info\fR
816 Ap_Id Information
817 px_pci7.pcie0 Location: px_pci7.pcie0
818 px_pci11.pcie0 Location: px_pci11.pcie0
819 px_pci11.pcie0:iob.pcie1 Location: px_pci11.pcie0/iob.pcie1
820 px_pci11.pcie0:iob.pcie2 Location: px_pci11.pcie0/iob.pcie2
821 px_pci11.pcie0:iob.pcie3 Location: px_pci11.pcie0/iob.pcie3
822 .fi
823 .in -2
824 .sp
826 .sp
827 .LP
828 In this example, the host system contains two hotpluggable slots,
829 "px_pci7.pcie0" and "px_pci11.pcie0". In this case, it uses "slot-id form (3)"
830 ( the default form) for the base \fIslot-path\fR component in the
831 \fIabsolute-slot-path\fR because the framework could not obtain enough
832 information to produce other more descriptive forms of higher precedence.
834 .sp
835 .LP
836 Interpreting right-to-left, attachment point "px_pci7.pcie0" represents a PCI
837 Express slot with PCI device number 0 (which does not imply a physical slot
838 number of the same), bound to nexus driver "px_pci", instance 7. Likewise,
839 attachment point "px_pci11.pcie0" represents a PCI Express slot with PCI device
840 number 0 bound to driver instance 11 of px_pci.
842 .sp
843 .LP
844 Under "px_pci11.pcie0" is a third party expansion chassis without a
845 \fIserial-id\fR and with three hotpluggable PCI Express slots.
847 .sp
848 .LP
849 The following command shows a listing for a topology with attachment point
850 paths exceeding the \fIApId\fR field length limit:
852 .sp
853 .in +2
854 .nf
855 example# \fBcfgadm -s cols=ap_id:info\fR
857 Ap_Id Information
858 pcie4 Location: pcie4
859 pcie4:iobSUNW.pcie1 Location: pcie4/iobSUNW.pcie1
860 pcie4:iobSUNW.pcie2 Location: pcie4/iobSUNW.pcie2
861 iob8879c3f3.pci1
862 Location: pcie4/iobSUNW.pcie2/iob8879c3f3.pci1
863 iob8879c3f3.pci2
864 Location: pcie4/iobSUNW.pcie2/iob8879c3f3.pci2
865 iob8879c3f3.pci3
866 Location: pcie4/iobSUNW.pcie2/iob8879c3f3.pci3
867 .fi
868 .in -2
869 .sp
871 .sp
872 .LP
873 In this example, there is only one hotpluggable slot, "pcie4" in the host.
874 Connected under "pcie4" is a SUN expansion chassis with FRU identifier "SUNW".
875 Nested under PCI Express slot "pcie2" of that expansion chassis (ApId
876 pcie4:iobSUNW.pcie2) lies another expansion chassis with three hotpluggable PCI
877 slots.
879 .sp
880 .LP
881 Because the length of the \fIabsolute-slot-path\fR form of
882 "pcie4/iobSUNW.pcie2/iob8879c3f3.pci1...3" exceeds the \fIApId\fR field length
883 limit, and the leaf \fIslot-path\fR component is globally unique, "ap_id form
884 (2)" is used, where the leaf \fIslot-path\fR component in the
885 \fIabsolute-slot-path\fR is used as the final \fIApId\fR.
887 .sp
888 .LP
889 The following command shows a listing for a topology with attachment point
890 paths exceeding the \fIApId\fR field length limit and lacking enough
891 information to uniquely identify the leaf \fIslot-id\fR on its own (for
892 instance, missing the \fIserial-id\fR):
894 .sp
895 .in +2
896 .nf
897 example# \fBcfgadm -s cols=ap_id:info\fR
900 Ap_Id Information
901 pcie4 Location: pcie4
902 pcie4:iob4567812345678.pcie3 Location: pcie4/iob4567812345678.pcie3
903 px_pci20.pcie0
904 Location: pcie4/iob4567812345678.pcie3/iob.pcie1
905 px_pci21.pcie0
906 Location: pcie4/iob4567812345678.pcie3/iob.pcie2
907 .fi
908 .in -2
909 .sp
911 .sp
912 .LP
913 In this example, there is only one hotpluggable slot, "pcie4" in the host.
914 Connected under "pcie4" is a third party expansion chassis with hexadecimal
915 \fIserial-id\fR 4567812345678. Nested under the PCI Express slot "pcie3" of
916 that expansion chassis (ApId pcie4:iob4567812345678.pcie3), lies another third
917 part expansion chassis without a \fIserial-id\fR and with two hotpluggable PCI
918 Express slots.
920 .sp
921 .LP
922 Because the length of the \fIabsolute-slot-path\fR form of
923 "pcie4/iob4567812345678.pcie3/iob.pcie1...2" exceeds the \fIApId\fR field
924 length limit, and the leaf \fIslot-path\fR component is not globally unique,
925 "ap_id form (3)" is used. "ap_id form (2)" is where \fIslot-id\fR form (3)
926 (default form) of the leaf \fIslot-path\fR component in the
927 \fIabsolute-slot-path\fR is used as the final \fIApId\fR.
929 .sp
930 .LP
931 The default form or "slot-id form (3)" of the leaf component
932 ".../iob.pcie1"represents a PCI Express slot with device number 0, bound to
933 driver instance 20 of "px_pci". Likewise, the default form of the leaf
934 component ".../iob.pcie2" represents a PCI Express slot with device number 0,
935 bound to driver instance 21 of "px_pci"
937 .SH FILES
938 .sp
939 .ne 2
940 .na
941 \fB/usr/lib/cfgadm/pci.so.1\fR
942 .ad
943 .sp .6
944 .RS 4n
945 Hardware specific library for PCI hot plugging.
946 .RE
948 .SH SEE ALSO
949 .sp
950 .LP
951 \fBcfgadm\fR(1M), \fBconfig_admin\fR(3CFGADM), \fBlibcfgadm\fR(3LIB),
952 \fBattributes\fR(5)
953 .sp
954 .LP
955 \fI\fR