pciconfig(1M)
pciconfig - hot-plug insert, hot-plug remove, and query PCI devices
As shipped in IRIX 6.5.19. Last changed in IRIX 6.5.19.
NAME pciconfig - hot-plug insert, hot-plug remove, and query PCI devices SYNOPSIS pciconfig -b bus_path_name {-u | -d | -q} [-v] [-o] [-x] [-s slot_number] DESCRIPTION pciconfig 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. -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: ./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 Prick 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 Prick or Ibrick, i.e. a brick that is attached to two Cbricks, locate both Cbricks to which the Prick or Ibrick is attached. Note the module-ID of each Cbrick 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/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: 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 ALSO ioconfig(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.