cfgadm_shp(1M)
名称
cfgadm_shp - 特定于 PCI Express 和标准 PCI 热插拔硬件的 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] -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]
描述
将 PCI Express 和标准 PCI 热插拔适配卡热插到允许热插拔系统中的相应可热插拔插槽中时，特定于 PCI Express 和标准 PCI 热插拔硬件的库 /usr/lib/cfgadm/shp.so.1 可通过 cfgadm 命令（请参见 cfgadm(1M)）提供相关支持。cfgadm_pci 库（请参见 cfgadm_pci(1M)）提供对其他 PCI 热插拔适配卡（除 PCI Express 和标准 PCI 热插拔卡之外的其他卡）的支持。除了本手册页中标注的以外，介于 PCI Express 热插拔和标准 PCI 热插拔之间的热插拔管理模型仍是相同的。
对于 PCI 热插拔，特定 PCI 总线上的每个热插拔槽均可由该 PCI 总线的一个连接点来表示。
一个连接点由一个插口和一个插卡组成。PCI 热插拔下的插口通常指物理可热插拔槽；插卡通常指插入插槽的 PCI 适配卡。
连接点通过 ap_id 命名。有两种类型的 ap_id：逻辑 ap_id 和物理 ap_id。物理 ap_id 基于物理路径名，例如：
/devices/pci@7c,0/pci10de,5d@d:pcie2
而逻辑 ap_id 是更为简短、更加用户友好的名称，例如 pcie2。热插拔 PCI 的 ap_type 为 pci。
请注意，ap_type 与 Type（类型）字段中的信息不同。
PCI Express ap_id 命名
对于位于 PCI Express 分层结构（也就是说，父或祖先为 PCI Express 设备）中的连接点（包括本身不属于 PCI Express 设备连接点），将使用下面显示的命名模式。
语法：
- APID : absolute-slot-path
基本术语。
- absolute-slot-path : slot-path[:slot-path[:slotpath ...]]
...其中 fru-id 表示包含 slot-id 的机箱 FRU（如果有）。
- fru-id : fru-type[serialid#]
...其中 fru-type 为 PCI Express 扩展机箱的 "iob"，后接序列号 serialid#（如果提供）
- slot-id : slot-name | device-type physical-slot# | \
- nexus-driver-name nexus-driver-instance.\
- device-type pci-device-number
...其中 slot-name 为平台或硬件自行分配的名称。device-type 为 pcie（对于 PCI Express 设备）或 pci（对于 PCI 设备）。nexus-driver-name 为设备组件的驱动程序名称，physical-slot# 为硬件槽号，而 pci-device-number 为按标准 PCI 命名规则命名的 PCI 设备编号。
首先将构造 absolute-slot-path，以便使用在用户看来更易于实际确认的术语来描述连接点的拓扑位置。此 absolute-slot-path 包含由 :（冒号）分隔的 slot-path 组件。叶或最左侧的 slot-path 组件描述的是连接点设备本身，而其右侧相邻的 slot-path 组件直至最右侧或最顶端的 slot-path 组件分别描述从父设备到根设备的各种设备。
每个 slot-path 均含 slot-id（可选择性地在前面添加 fru-id，该 ID 用于标识内含 slot-id（详见下）所描述设备的扩展机箱）。fru-id 包含 fru-type，后跟可选的 serialid#。PCI Express 扩展机箱类型的 fru-type 为 "iob"，而 serialid# 既可以是从扩展机箱硬件中获取的 64 位十六进制数（表示原始序列号），也可以是大写的适用于 Sun 品牌扩展机箱的 ASCII 四字符序列。
每个 slot-id 均包含下述三个可能的格式之一：
- slot-id 格式 (1)
slot-names
- slot-id 格式 (2)
device-type physical-slot#
- slot-id 格式 (3)
nexus-driver-name nexus-driver-instance device-type pci-device-number
在选择具体格式时，将按照格式编号从最低到最高的优先顺序进行选择，也可以自上而下地进行选择（如上所述）。如果无法成功构造某个格式，则会尝试下一个编号较高的格式。
slot-id 格式 (1) 中的 slot-names 是从设备树中对应节点的 slot-names 属性获取的，是由硬件或平台分配的名称。此格式尚未预定义或建立。
在 slot-id 格式 (2) 中，device-type 表示组件插槽的设备类型，其值为 pcie（对于 PCI Express）或 pci（对于 PCI），而从对应设备节点的 physical-slot# 属性获取的 physical-slot# 表示组件的硬件槽号。
当其他所有格式均无法成功构造时，将使用 slot-id 格式 (3)，并被认为是缺省格式。nexus-driver-name 是组件的驱动程序名称；nexus-driver-instance 是该驱动程序的实例；device-type 与格式 (2) 中描述的相同；pci-device-number 是所述的 PCI 设备编号，用于按照标准 PCI 命名规则命名的设备配置循环。
在对 slot-path 组件进行总结时，我们会发现该组件是对可选 FRU 组件（可能位于该组件之前）的扩展，具体说来，slot-path 将包含以下按顺序排列的格式之一：
- (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
最后，在 cfgadm 中实际使用的 ap_id 名称的最终格式确定如下（按优先级顺序指定）：
- ap_id 格式 (1)
如果 absolute-slot-path 的长度在 cfgadm 的 ap_id 字段的固定长度限制之内，则只需使用 absolute-slot-path。
- ap_id 格式 (2)
（absolute-slot-path 的长度超过 ap_id 的长度限制）如果最后一个 slot_path 组件包含在扩展机箱中，且该组件包含 serialid#，则使用这最后一个 slot_path 组件。此格式要求使用 serialid# 是为了确保 ap_id 在全局范围内都是唯一的。
- ap_id 格式 (3)
（absolute-slot-path 的长度超过 ap_id 的长度限制）将使用最后一个 slot_path 组件的缺省格式，即 slot-id 格式 (3)。
不管使用哪一个最终的 ap_id 名称，absolute-slot-path 都将存储在能够使用 –s 或 –v 选项显示的 "Information"（信息）(info) 字段中。此信息可用来对任何使用 ap_id 格式 (2) 或 ap_id 格式 (3) 命名的 ap_id 进行物理定位。将 absolute-slot-path 存储在信息字段中时会进行稍许变换，即使用正斜杠 (/) 替换冒号 (:)，以便更准确地指示拓扑上下文。absolute-slot-path 可能包括叶或最右侧 slot-path 组件（直至板载主机槽）上面不属于热插拔组件的 slot-path 组件。
有关可热插拔组件的示例列表，请参见“示例”部分。
选项
支持以下选项：
- –c function
以下函数可用于 PCI 可热插拔插槽：
- configure
将 PCI 设备配置在 Solaris 使用的插槽中。
- connect
将插槽与 PCI 总线相连。
- disconnect
断开插槽与 PCI 总线之间的连接。
- insert
不支持。
- remove
不支持。
- unconfigure
将 PCI 设备的资源从系统中逻辑移除。
- –f
不支持。
- –h ap_id | ap_type
显示特定于 PCI 热插拔的帮助消息。
- –l list
列出 PCI 热插拔插槽的值。
- –o hardware_options
当前没有定义任何硬件专用选项。
- –s listing_options
与通用的 cfgadm(1M) 相同。
- –t ap_id
此命令只适用于支持插槽测试功能的平台。
- –v
在详细模式下执行。
如果 –v 选项与 –l 选项一起使用，cfgadm 命令输出有关连接点的信息。对于 PCI Express 分层结构中的连接点，"Information"（信息）字段将包含连接点的绝对插槽路径位置，包括插槽路径中每个组件的任何特定于硬件或平台的标记信息。插槽路径中的每个组件将通过 /（正斜杠）分隔。请参见上面的“PCI Express ap_id 命名”。有关不在 PCI Express 分层结构中的 PCI 热插拔连接点的内容，请参见 cfgadm_pci(1M)。Type（类型）字段中的信息可使用 –v 选项列出，也可不使用该选项列出。插卡的 Type（类型）字段描述有关插槽的信息。有两个可能的值：
- unknown（未知）
该插槽为空。如果该插槽中安装了卡，表明该卡未配置或卡上的设备未安装驱动程序。
- subclass/board
该插槽中的卡是一个单功能或多功能设备。
subclass 是表示设备子类代码的字符串，例如 SCSI、ethernet、pci-isa 等。如果该卡为多功能设备，则将改为显示 MULT。
board 是表示设备的板类型的字符串。例如，hp 是用于 PCI 热插拔适配器的字符串。
- –x hardware_function
执行特定于硬件的函数。这些特定于硬件的函数通常不会更改插口或插卡的状态。
支持以下 hardware_function：
- led=[led_sub_arg],mode=[mode_sub_arg]
在没有子参数的情况下，将显示当前 LED 指示灯设置的列表。在有子参数的情况下，将为插槽设置特定 LED 指示灯的模式。
将 led_sub_arg 指定为 fault、power、attn 或 active。
将 mode_sub_arg 指定为 on、off 或 blink。
对于 PCI Express，只有 power 和 attn LED 指示灯是有效的，只有 attn LED 指示灯的状态可以更改。
更改 LED 指示灯的状态不会更改插口或插卡的状态。通常，LED 指示灯由热插拔控制器控制，无需用户干预。使用该命令用于测试目的。
注意 - 更改 LED 指示灯的状态可能导致插卡或插口的状态显示错误。
以下命令可显示 LED 指示灯的值：
example# cfgadm -x led pcie2 Ap_Id Led pcie2 power=on,fault=off,active=off,attn=off
以下命令将 attn LED 指示灯设置为 blink，以指示插槽的位置：
example# cfgadm -x led=attn,mode=blink pcie2
示例
示例 1 显示每个插槽的值以下命令可显示每个插槽的值：
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示例 2 替换卡
以下命令列出所有支持 DR 的连接点：
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
以下命令可取消对 pcie7 所标识的卡的配置并以电子方式断开其连接：
example# cfgadm -c disconnect pcie7
该更改可通过输入以下命令验证：
example# cfgadm pcie7 Ap_Id Type Receptacle Occupant Condition pcie7 unknown disconnected unconfigured unknown
此时可换卡。以下命令可通过电子方式连接并配置替换卡：
example# cfgadm -c configure pcie7
该更改可通过输入以下命令验证：
example# cfgadm pcie7 Ap_Id Type Receptacle Occupant Condition pcie7 etherne/hp connected configured ok示例 3 解释 PCI Express 拓扑中的 ApId
以下命令显示了 I/O 扩展机箱在连接到主机级可热插拔插槽后，其中的 PCI Express 和 PCI 连接点的拓扑列表：
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
在本示例中，iou#0-pci#[0-3] 项表示系统中最顶端的可热插拔插槽。由于 iou#n-pci#n 格式与上述语法规范部分中描述的任何一种格式都不匹配，因此我们可以推断，此热插拔拓扑中基本组件的这种名称是通过 slot-names 属性由平台指定的。
上述输出中的插槽描述如下：
- 插槽 iou#0-pci#0
此插槽为空或其插卡未配置。
- 插槽 iou#0-pci#1
此插槽包含一个带两个可热插拔插槽（pci3 和 pci4）的扩展机箱。pci3 和 pci4 表示两个包含在该扩展机箱内的 PCI 插槽，其物理槽号分别为 3 和 4。此处的扩展机箱既没有也不导出 serial-id（序列号）。
- 插槽 iou#0-pci#2
此插槽包含一个十六进制 serial-id（序列号）为 58071 的第三方扩展机箱。该扩展机箱内有两个可热插拔插槽 pcie1 和 special。pcie1 表示 PCI Express 插槽，其物理槽号为 1。插槽 special 带有一个源自平台、硬件或固件的标签。
- 插槽 iou#0-pci#3
此插槽包含一个 FRU 标识符为 BADF 的 Sun 扩展机箱。此扩展机箱包含三个 PCI Express 插槽 pcie1、pcie2 和 pcie3，物理槽号分别为 1、2、3，以及两个 PCI 插槽 pci1 和 pci2，物理槽号分别为 1 和 2。
以下命令显示了 I/O 扩展机箱（带连接的可热插拔和非热插拔主机槽）中的 PCI Express 和 PCI 连接点的拓扑列表：
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
在本示例中，主机系统只有一个可热插拔插槽 Slot1。我们可以推断 Slot2 和 Slot5 不属于可热插拔插槽，因为这两个插槽在 cfgadm 中没有自行显示为连接点。不过，Slot2 和 Slot5 都包含带可热插拔插槽的第三方扩展机箱。
以下命令显示了缺少特定设备属性的连接点的拓扑列表：
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
在本示例中，主机系统包含两个可热插拔插槽 px_pci7.pcie0 和 px_pci11.pcie0。在这种情况下，系统会将 slot-id 格式 (3)（缺省格式）用于 absolute-slot-path 中的 slot-path 基本组件，因为框架无法获取足够的信息以生成其他优先级更高的、更具描述性的格式。
自右至左进行解释时，连接点 px_pci7.pcie0 表示 PCI 设备编号为 0（这并不表示物理槽号也是这一编号）且已绑定到结点驱动程序 px_pci 实例 7 上的 PCI Express 插槽。类似地，连接点 px_pci11.pcie0 表示 PCI 设备编号为 0 且已绑定到 px_pci 的驱动程序实例 11 上的 PCI Express 插槽。
在 px_pci11.pcie0 下是带三个可热插拔 PCI Express 插槽但没有 serial-id 的第三方扩展机箱。
以下命令显示了超过 ApId 字段长度限制的连接点路径拓扑列表：
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
在本示例中，主机中只有一个可热插拔插槽 pcie4。在 pcie4 下连接的是一个 FRU 标识符为 SUNW 的 Sun 扩展机箱。嵌套在该扩展机箱 (ApId pcie4:iobSUNW.pcie2) PCI Express 插槽 pcie2 下的是另一个带三个可热插拔 PCI 插槽的扩展机箱。
对于以下项的 absolute-slot-path 格式：
pcie4/iobSUNW.pcie2/iob8879c3f3.pci1...3
由于其长度超过 ApId 字段的长度限制，且叶 slot-path 组件是全局唯一的，因此将使用 ap_id 格式 (2)，其中，absolute-slot-path 中的叶 slot-path 组件将用作最终 ApId。
以下命令显示了路径的拓扑列表，其中的连接点路径超过 ApId 字段的长度限制，且缺少自行对叶 slot-id 进行唯一标识所需的足够信息（例如，缺少 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
在本示例中，主机中只有一个可热插拔插槽 pcie4。在 pcie4 下连接的是十六进制 serial-id（序列号）为 4567812345678 的第三方扩展机箱。嵌套在该扩展机箱 (ApId pcie4:iob4567812345678.pcie3) PCI Express 插槽 pcie3 下的是另一个带两个可热插拔 PCI Express 插槽但没有 serial-id（序列号）的第三方扩展机箱。
对于以下项的 absolute-slot-path 格式：
pcie4/iob4567812345678.pcie3/iob.pcie1...2
由于其长度超过 ApId 字段的长度限制，且叶 slot-path 组件不是全局唯一的，因此将使用 ap_id 格式 (3)。在 ap_id 格式 (2) 中，将使用 absolute-slot-path 中叶 slot-path 组件的 slot-id 格式 (3)（缺省格式）作为最终 ApId。
叶组件 .../iob.pcie1 的缺省格式或 slot-id 格式 (3) 表示设备编号为 0 且已绑定到 px_pci 的驱动程序实例 20 的 PCI Express 插槽。类似地，叶组件 .../iob.pcie2 的缺省格式表示设备编号为 0 且已绑定到 px_pci 的驱动程序实例 21 的 PCI Express 插槽。
文件
- /usr/lib/cfgadm/shp.so.1
适用于 PCI Express 和标准 PCI 热插拔的特定于硬件的库。
属性
有关下列属性的说明，请参见 attributes(5)：
|
另请参见
cfgadm(1M)、cfgadm_pci(1M)、hotplugd(1M)、config_admin(3CFGADM)、libcfgadm(3LIB)、attributes(5)、smf(5)
附注
cfgadm_shp 库依赖于 hotplug 服务，而该服务由 smf(5) 进行管理，其 FMRI（故障管理资源标识符）如下：
svc:/system/hotplug:default
要想正常运行 cfgadm_shp 库，必须启用该服务。有关详细信息，请参见 hotplugd(1M)。