pciconfig(1M)pciconfig(1M)NAMEpciconfig - hot-plug insert, hot-plug remove, and query PCI devices
SYNOPSISpciconfig-b bus_path_name {-u | -d | -q} [-v] [-o] [-x] [-s slot_number]
DESCRIPTIONpciconfig is used to hot-plug insert a device into a PCI slot, hot-plug
remove a device from a PCI slot, and query a slot on a PCI bus controlled
by a bridge device. PCI Hot-Plug operations are executed while the
system is running.
A hot-plug insertion powers-up the PCI slot, determines the type of card
installed, and calls the appropriate device driver to initialize the card
and its software. Typically, after a successful hot-plug insertion, new
device entries will be found in the hardware graph. The card can then be
used as if it were in the system at boot time.
A hot-plug removal calls the appropriate device driver to terminate card
operation and release software resources used by the device. The PCI
slot is then powered-down. Typically, after a successful hot-plug
removal, the device entries will be removed from the hardware graph.
The hot-plug insert operation calls the device driver's attach function
and the hot-plug removal operation calls the device driver's detach
function. Each function must completely initialize or terminate both
hardware and software device operation for the insertion or removal to be
successful. If a driver does not completely handle attaching or
detaching its device, a system failure may occur.
Individual device drivers may support hot-plug insertion, hot-plug
removal, neither, or both. If a driver supports both hot-plug insertion
and removal, then cards supported by that driver can be replaced in a
running system. Only certified device drivers support PCI Hot-Plug
operations; attempts to hot-plug insert or remove a card that does not
have a certified driver will fail.
System critical slots may not be hot-plug removed.
Unless the -o option is used, hot-plug inserting a card into a slot
automatically executes the ioconfig command to assign a global
unit/controller number to the slot's device.
The options are:
-b bus_path_name
Specify the hardware graph path name of the target PCI bus in which
the target device is installed. This path name will be concatenated
with the device name "controller" to form the full path name of the
bridge device that manages the target PCI bus.
Page 1
pciconfig(1M)pciconfig(1M)-u Hot-plug insert a card into the specified slot on the target bus.
An insert operation consists of supplying power to the slot,
initializing the bridge hardware and kernel software for the slot,
and calling the device driver attach function that is registered to
support the device installed in the slot. Unless the -o option is
also specified, the ioconfig command is then executed to assign a
global unit/controller number to the device in the slot. After a
successful insertion, the slot device status is "start-up complete"
and the slot power status is "up". The slot device status following
an unsuccessful insertion is "start-up incomplete".
-d Hot-plug remove a card from the specified slot on the target bus. A
remove operation consists of calling the device driver detach
function that supports the device installed in the slot, reseting
the bridge hardware and kernel software for the slot, and removing
power from the slot. After a successful removal, the slot device
status is "shut-down complete" and the slot power status is "down".
The slot device status following an unsuccessful removal is "shut-
down incomplete".
-q Query the specified slot, or if no slot is specified, query all the
slots on the target bus. The response includes the slot device
status, the slot power status, the speed of the bus, and whether or
not the slot is system critical.
-v Use verbose mode; for a query, additional slot information is
displayed. For hot-plug insertion, displays the ioconfig command
that will be executed to assign a global unit/controller number to
the device after it is initialized by its driver.
-o Used with hot-insertion option (-u) to only initialize the card and
its software, but not execute the ioconfig command that assigns a
global unit/controller number to the PCI device. The ioconfig
command must be manually executed to assign a global unit/controller
number to the device.
-x Enables ioconfig command debugging by using the -d option during
ioconfig command execution. The ioconfig command is executed to
assign a global unit/controller number to the device after it has
been successfully initialized.
-s slot_number
Specify a slot on the target PCI bus in which the target device is
installed. Required for hot-plug insertion and removal operations,
and optional for queries.
ERROR MESSAGES
Attempting to hot-plug insert a card into a slot that is already
started-up, hot-plug remove a card from a slot that is already shut-down,
or hot-plug remove a system critical slot is not permitted and results in
a message similar to one of these:
Page 2
pciconfig(1M)pciconfig(1M)
./pciconfig: PCI slot start-up ioctl() failed for:
/hw/module/006c05/Pbrick/xtalk/14/pci/controller[slot 2]
: Operation not permitted
Slot #2 may already be started-up
./pciconfig: PCI slot shut-down ioctl() failed for:
/hw/module/006c05/Pbrick/xtalk/14/pci/controller[slot 2]
: Operation not permitted
Slot #2 may already be shut-down or may be system critical
FILES
The -b option specifies the hwgraph path name of the PCI bus in which the
device is to be hot-plug inserted or removed. The bus path name to use
can be found using either of these two procedures.
Method #1.
Physically locate the Pbrick or Ibrick containing the PCI slot that is to
be the target of the hot-plug insertion or removal. Viewing the Pbrick
or Ibrick from the rear, note the target slot's bus and slot number using
the label at the top of the slot.
For a single ported Pbrick or Ibrick, i.e. a brick that is attached to
only one Cbrick, locate the Cbrick to which the Pbrick or Ibrick is
attached. Note that Cbrick's module-ID from its LED display on the front
of the brick.
Search the hardware graph for all the PCI buses in the system:
find /hw -type d -name bus
/hw/module/001c10/Ibrick/bus
/hw/module/001c21/Pbrick/bus
From the list of PCI buses, select the hardware graph path name that
contains the edge label "Pbrick" or "Ibrick" and that matches the
Cbrick's module-ID. Assuming that the target slot is in a Pbrick
attached to a Cbrick with an module-ID of "001c21", the controlling
Cbrick hardware graph path name is:
/hw/module/001c21/Pbrick/bus
For a dual ported Pbrick or Ibrick, i.e. a brick that is attached to two
Cbricks, locate both Cbricks to which the Pbrick or Ibrick is attached.
Note the module-ID of each Cbrick from its LED display on the front of
the brick.
Page 3
pciconfig(1M)pciconfig(1M)
Search the hardware graph for all the PCI buses in the system:
find /hw -type d -name bus
/hw/module/001c10/Ibrick/bus
/hw/module/001c13/Pbrick/bus
/hw/module/001c21/Pbrick/bus
From the list of PCI buses, select the hardware graph path names that
contain the edge label "Pbrick" or "Ibrick" and that match either of the
Cbrick module-IDs. Assuming that the target slot is in a Pbrick attached
to two Cbricks, one with a module-ID of "001c13" and the other with a
module-ID of "00c1c21", the hardware graph path names selected are:
/hw/module/001c13/Pbrick/bus
/hw/module/001c21/Pbrick/bus
List the numbers of all the PCI buses controlled by each Cbrick:
ls /hw/module/001c13/Pbrick/bus
2 4 6
ls /hw/module/001c21/Pbrick/bus
1 3 5
Select the path name that controls the target PCI bus number. Assuming
the target is bus number 3 the controlling Cbrick hardware graph path
name is:
/hw/module/001c21/Pbrick/bus
Use the controlling Cbrick path name for either a single or dual ported
brick to complete the hardware graph name of the PCI bus. Concatenate
the bus number to the controlling Cbrick path name. Assuming the target
slot is in bus 3, the PCI bus path name to use as the -b option is:
/hw/module/001c21/Pbrick/bus/3
Use the PCI slot number as the -s option.
Method #2.
The full hwgraph path name for a target PCI device can be found by
searching for part of the device's path name, e.g. for a SCSI controller
device:
Page 4
pciconfig(1M)pciconfig(1M)
find /hw -name '*scsi*'
/hw/module/001c21/Pbrick/xtalk/15/pci/1/scsi_ctlr
/hw/module/001c21/Pbrick/xtalk/15/pci/1/scsi_ctlr/0/target/1/lun/0/scsi
/hw/scsi_ctlr
/hw/scsi
Inspect the full device path names up to and including the edge labeled
"pci". Form the PCI bus path name by truncating all of the path name to
the right of the edge labeled "pci". In this case for the SCSI
controller device, the PCI bus path name to use as the -b option is:
/hw/module/001c21/Pbrick/xtalk/15/pci
The PCI slot number for the device is the edge label immediately
following the edge labeled "pci" in the target device's full path name.
For this SCSI controller device, it is PCI slot number 1. This is the
value to use with the -s option.
SEE ALSOioconfig(1M).
NOTE
The PCI Hot-Plug feature has some restrictions. Only 66 MHz cards can be
inserted into an empty bus in a Pbrick or Ibrick, and the last card
cannot be removed from a bus running at 33 MHz in a Pbrick or Ibrick.
Cards inserted into a bus where another card is already installed will
run at the bus speed already set for the installed card. If inserting
the new card would result in a bus speed mis-match with the existing
card, the hot-insertion is failed. Since a Pbrick has six buses with two
slots each, it can be populated at boot time to accommodate insertion of
cards running at 33 and 66 MHz.
Page 5
