svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
cfgadm_shp(8)
System Administration Commands cfgadm_shp(8)
NAME
cfgadm_shp - PCI Express and Standard PCI 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] -x hardware_function ap_id [ap_id]
/usr/sbin/cfgadm [-v] [-o hardware_options] -tap_id [ap_id]
/usr/sbin/cfgadm [-v] [-o hardware_function]-h [ap_id | ap_type]
DESCRIPTION
The PCI Express and Standard PCI Hotplug hardware-specific library,
/usr/lib/cfgadm/shp.so.1, provides support for hotplugging PCI Express
and Standard PCI Hotplug adapter cards into the respective hotpluggable
slots in a system that is hotplug-capable, through the cfgadm command
(see cfgadm(8)). Support for the rest PCI Hotplug adapter cards (other
than PCI Express and Standard PCI Hotplug cards) are provided by
cfgadm_pci library (see cfgadm_pci(8)). Hotplug administrative models
between PCI Express Hotplug and Standard PCI Hotplug remain the same
except where noted in this man page.
For PCI hotplug, each hotplug slot on a specific PCI bus is represented
by an attachment point of that PCI bus.
An attachment point consist of two parts: a receptacle and an occupant.
The receptacle under PCI hotplug 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 physi‐
cal pathname, for example:
/devices/pci@7c,0/pci10de,5d@d:pcie2
Whereas the logical ap_id is a shorter, more user-friendly name, for
example, pcie2. The ap_type for Hotplug PCI is pci.
Note that the ap_type is not the same as the information in the Type
field.
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 that are not PCI Express devices themselves, the naming scheme
shown below is used.
Grammar:
APID : absolute-slot-path
Fundamental term.
absolute-slot-path : slot-path[:slot-path[:slotpath ...]]
...where fru-id indicates the chassis FRU, if any, containing the
slot-id.
fru-id : fru-type[serialid#]
...where fru-type is "iob" for a 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 nomen‐
clature.
First, an absolute-slot-path is constructed that attempts to describe
the attachment point's topological location in more physically identi‐
fiable terms for the user. This absolute-slot-path consists of slot-
path components each separated by a : (colon). The leaf or leftmost
slot-path component describes the device of the attachment point
itself, while its right-adjacent slot-path component up to the right‐
most or topmost slot-path component describes the parent up to the root
devices, respectively.
Each slot-path consists of a slot-id optionally preceded by a fru-id,
which identifies 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 an
uppercase, ASCII four-character sequence for a 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 num‐
ber 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 prop‐
erty 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 com‐
ponent's slot, and is either pcie for PCI Express or pci for PCI, while
physical-slot#, taken from the physical-slot# property of its corre‐
sponding device node, indicates the hardware slot number of the compo‐
nent.
slot-id form (3) is used when all other forms cannot be successfully
constructed, and is considered to be the default form. nexus-driver-
name is the component's driver name; nexus-driver-instance is this
driver's instance; device-type is the same as described in form (2);
pci-device-number 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 com‐
ponent that might precede it, slot-path will consist one of the follow‐
ing 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 glob‐
ally 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 rightmost
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 hotpluggable slots:
configure
Configure the PCI device in the slot to be used by Solaris.
connect
Connect the slot to PCI bus.
disconnect
Disconnect the slot from the PCI bus.
insert
Not supported.
remove
Not supported.
unconfigure
Logically remove the PCI device's resources from the system.
-f
Not supported.
-h ap_id | ap_type
Display PCI hotplug-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 that 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 "PCI Express
ap_id Naming," above. For PCI Hot Plug attachment points not
located in a PCI Express hierarchy, see cfgadm_pci(8). The informa‐
tion 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 two 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-func‐
tion 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 displayed
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.
-x hardware_function
Perform hardware-specific function. These hardware-specific func‐
tions should not normally change the state of a receptacle or occu‐
pant.
The following hardware_function is supported:
led=[led_sub_arg],mode=[mode_sub_arg]
Without subarguments, display a list of the current LED set‐
tings. With subarguments, 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 hotplug 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 displays the values of LEDs:
example# cfgadm -x led pcie2
Ap_Id Led
pcie2 power=on,fault=off,active=off,attn=off
The following command sets the attn LED to blink to indicate
the location of the slot:
example# cfgadm -x led=attn,mode=blink pcie2
EXAMPLES
Example 1 Displaying the Value of Each Slot
The following command displays 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
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
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 identified by pcie7:
example# cfgadm -c disconnect pcie7
The change can be verified by entering the following command:
example# cfgadm pcie7
Ap_Id Type Receptacle Occupant Condition
pcie7 unknown disconnected unconfigured unknown
At this point the card can be swapped. The following command electri‐
cally connects and configures the replacement card:
example# cfgadm -c configure pcie7
The change can be verified by entering the following command:
example# cfgadm pcie7
Ap_Id Type Receptacle Occupant Condition
pcie7 etherne/hp connected configured ok
Example 3 Interpreting ApIds in a PCI Express Topology
The following command shows a listing for a topology with both PCI
Express and PCI attachment points in an 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] entries represents the topmost
hotpluggable slots in the system. Because the iou#n-pci#n form does not
match any of the forms stated in the grammar specification section
described above, 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.
The slots in the preceding output are described as follows:
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 con‐
tained within that expansion chassis with physical slot numbers 3
and 4, respectively. The expansion chassis in this case does not
have or export a serial-id.
Slot iou#0-pci#2
This slot contains a third-party expansion chassis with a hexadeci‐
mal serial-id of 58071. Within that expansion chassis are two hot‐
pluggable 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 an I/O expansion chassis with con‐
nected 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 hot‐
pluggable 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 abso‐
lute-slot-path, because the framework could not obtain enough informa‐
tion to produce other more descriptive forms of higher precedence.
Interpreting right-to-left, attachment point px_pci7.pcie0 represents a
PCI Express slot with PCIdevice number 0 (which does not imply a physi‐
cal slot number of the same number), 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 identi‐
fier SUNW. Nested under PCI Express slot pcie2 of that expansion chas‐
sis (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 compo‐
nent 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 exam‐
ple, 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-party 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) (the 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 num‐
ber 0, bound to driver instance 21 of px_pci.
FILES
/usr/lib/cfgadm/shp.so.1
Hardware-specific library for PCI Express and Standard PCI hotplug‐
ging.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Availabilitysystem/dynamic-reconfiguration _ Interface
StabilityUncommitted
SEE ALSO
config_admin(3CFGADM), libcfgadm(3LIB), attributes(7), smf(7),
cfgadm(8), cfgadm_pci(8), hotplugd(8)
NOTES
The cfgadm_shp library is dependent on the hotplug service, which is
managed by smf(7) under FMRI:
svc:/system/hotplug:default
The service must be enabled for the cfgadm_shp library to function
properly. See hotplugd(8) for details.
Oracle Solaris 11.4 11 May 2021 cfgadm_shp(8)