Chapter 6 Dynamically Configuring Devices (Tasks)

This chapter provides instructions for dynamically configuring devices in the Solaris OS. You can add, remove, or replace devices in the Solaris OS while the system is still running, if the system components support hot-plugging. If the system components do not support hot-plugging, you can reboot the system to reconfigure the devices.

For information on the procedures associated with dynamically configuring devices, see the following:

• SCSI Hot-Plugging With the cfgadm Command (Task Map)

• PCI or PCIe Hot-Plugging With the cfgadm Command (Task Map)

• Application Developer RCM Script (Task Map)

• System Administrator RCM Script (Task Map)

For information on hot-plugging USB devices with the cfgadm command, see Hot-Plugging USB Devices With the cfgadm Command.

For information on hot-plugging InfiniBand devices with cfgadm command, see Chapter 9, Using InfiniBand Devices (Overview/Tasks).

For information about accessing devices, see Accessing Devices.

Dynamic Reconfiguration and Hot-Plugging

Hot-plugging is the ability to physically add, remove, or replace system components while the system is running. Dynamic reconfiguration refers to the ability to hot-plug system components. This term also refers to the general ability to move system resources (both hardware and software) around in the system or to disable them in some way without physically removing them from the system.

Generally, you can hot-plug the following bus types:

• USB

• Fibre Channel

• 1394

• ATA

• SCSI

• Infiniband

In addition, you can hot-plug the following devices with the cfgadm command:

• USB devices on SPARC and x86 platforms

• SCSI devices on SPARC and x86 platforms

• PCI devices on SPARC and x86 platforms

• PCIe devices on SPARC or x86 platforms

• InfiniBand devices on SPARC and x86 devices

Features of the cfgadm command include the following:

• Displaying system component status

• Testing system components

• Changing component configurations

• Displaying configuration help messages

The benefit of using the cfgadm command to reconfigure systems components is that you can add, remove, or replace components while the system is running. An added benefit is that the cfgadm command guides you through the steps needed to add, remove, or replace system components.

For step-by-step instructions on hot-plugging components, see the following:

• SCSI Hot-Plugging With the cfgadm Command

• PCI or PCIe Hot-Plugging With the cfgadm Command

• cfgadm(1M)

Not all SCSI and PCI controllers support hot-plugging with the cfgadm command.

As part of Sun's high availability strategy, dynamic reconfiguration is expected to be used in conjunction with additional layered products, such as alternate pathing or fail over software. Both products provide fault tolerance in the event of a device failure.

Without any high availability software, you can replace a failed device by manually stopping the appropriate applications, unmounting noncritical file systems, and then proceeding with the add or remove operations.

Some systems have slots that hot-pluggable and slots that are not hot-pluggable. For information about hot-plugging devices on your specific hardware configuration, such as on enterprise-level systems, refer to your hardware configuration documentation.

Attachment Points

The cfgadm command displays information about attachment points, which are locations in the system where dynamic reconfiguration operations can occur.

An attachment point consists of the following:

• An occupant, which represents a hardware component that can be configured into the system

• A receptacle, which is the location that accepts the occupant

Attachment points are represented by logical and physical attachment point IDs (Ap_Ids). The physical Ap_Id is the physical path name of the attachment point. The logical Ap_Id is a user-friendly alternative for the physical Ap_Id. For more information on Ap_Ids, refer to cfgadm(1M).

The logical Ap_Id for a SCSI Host Bus Adapter (HBA), or SCSI controller, is usually represented by the controller number, such as c0.

In cases where no controller number has been assigned to a SCSI HBA, then an internally generated unique identifier is provided. An example of a unique identifier for a SCSI controller is the following:

fas1:scsi

The logical Ap_Id for a SCSI device usually has this format:

HBA-logical-apid::device-identifier

In the following example, c0 is the logical Ap_Id for the SCSI HBA:

c0::dsk/c0t3d0

The device identifier is typically derived from the logical device name for the device in the /dev directory. For example, a tape device with logical device name, /dev/rmt/1, has the following logical Ap_Id:

c0::rmt/1

If a logical Ap_Id of a SCSI device cannot be derived from the logical name in the /dev directory, then an internally generated unique identifier is provided. An example of an identifier for the /dev/rmt/1 tape device is the following:

c0::st4

For more information on SCSI Ap_Ids, refer to cfgadm_scsi(1M).

The cfgadm command represents all resources and dynamic reconfiguration operations in terms of a common set of states (such as configured and unconfigured) and operations (such as connect, configure, unconfigure, and so on). For more information on these common states and operations, see cfgadm(1M).

The following table shows the receptacle and occupant states for the SCSI HBA attachment points.

The following table shows the receptacle and occupant states for SCSI device attachment points.

The state of SCSI attachment points is unknown unless special hardware indicates otherwise. For instructions on displaying SCSI component information, see How to Display Information About SCSI Devices.

Detaching PCI or PCIe Adapter Cards

A PCI adapter card that is hosting nonvital system resources can be removed if the device driver supports hot-plugging. A PCI adapter card is not detachable if it is a vital system resource. For a PCI adapter card to be detachable, the following conditions must be met:

• The device driver must support hot-plugging.

• Critical resources must be accessible through an alternate pathway.

For example, if a system has only one Ethernet card installed in it, the Ethernet card cannot be detached without losing the network connection. This detachment requires additional layered software support to keep the network connection active.

Attaching PCI or PCIe Adapter Cards

A PCI adapter card can be added to the system as long as the following conditions are met:

• There are slots available.

• The device driver supports hot-plugging for this adapter card.

For step-by-step instructions on adding or removing a PCI adapter card, see PCI or PCIe Hot-Plugging With the cfgadm Command.

SCSI Hot-Plugging With the cfgadm Command (Task Map)

SCSI Hot-Plugging With the cfgadm Command

This section describes various SCSI hot-plugging procedures that you can perform with the cfgadm command.

The SCSI framework generally supports hot-plugging of SCSI devices. However, you should consult your hardware documentation to confirm whether hot-plugging is supported for your SCSI devices.

These procedures use specific devices as examples to illustrate how to use the cfgadm command to hot-plug SCSI components. The device information that you supply, and that the cfgadm command displays, depends on your system configuration.

How to Display Information About SCSI Devices

The following procedure uses SCSI controllers c0 and c1 and the devices that are attached to them in the examples of the type of device configuration information that you can display with the cfgadm command.

If the SCSI device is not supported by the cfgadm command, the device does not display in the cfgadm command output.

1. Become superuser.

2. Display information about attachment points on the system.

   # cfgadm -l Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c1 scsi-bus connected configured unknown

   In this example, c0 and c1 represent two SCSI controllers.

3. Display information about a system's SCSI controllers and their attached devices.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 unavailable connected unconfigured unknown

   ---

   Note –

   The cfgadm -l commands displays information about SCSI HBAs but not SCSI devices. Use the cfgadm -al command to display information about SCSI devices such as disk and tapes.

   ---

How to Unconfigure a SCSI Controller

The following procedure uses SCSI controller c1 in the example of unconfiguring a SCSI controller.

1. Become superuser.

2. Unconfigure a SCSI controller.

   # cfgadm -c unconfigure c1

3. Verify that the SCSI controller is unconfigured.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected unconfigured unknown

   Notice that the Occupant column for c1 specifies unconfigured, indicating that the SCSI bus has no configured occupants.

   If the unconfigure operation fails, see How to Resolve a Failed SCSI Unconfigure Operation.

How to Configure a SCSI Controller

The following procedure uses SCSI controller c1 in the example of configuring a SCSI controller.

1. Become superuser.

2. Configure a SCSI controller.

   # cfgadm -c configure c1

3. Verify that the SCSI controller is configured.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 unavailable connected unconfigured unknown

   The previous unconfigure procedure removed all devices on the SCSI bus. Now all the devices are configured back into the system.

How to Configure a SCSI Device

The following procedure uses SCSI disk c1t4d0 in the example of configuring a SCSI device.

1. Become superuser.

2. Identify the device to be configured.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 unavailable connected unconfigured unknown

3. Configure the SCSI device.

   # cfgadm -c configure c1::dsk/c1t4d0

4. Verify that the SCSI device is configured.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk connected configured unknown

How to Disconnect a SCSI Controller

Disconnecting a SCSI device must be done with caution, particularly when you are dealing with controllers for disks that contain critical file systems such as root (/), usr, var, and the swap partition. The dynamic reconfiguration software cannot detect all cases where a system hang might result. Use this procedure with caution.

The following procedure uses SCSI controller c1 in the example of disconnecting a SCSI device.

1. Become superuser.

2. Verify that the device is connected before you disconnect it.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk connected configured unknown

3. Disconnect the SCSI controller.

   # cfgadm -c disconnect c1 WARNING: Disconnecting critical partitions may cause system hang. Continue (yes/no)? y

   ---

   Caution –

   This command suspends all I/O activity on the SCSI bus until the cfgadm -c connect command is used. The cfgadm command does some basic checking to prevent critical partitions from being disconnected, but it cannot detect all cases. Inappropriate use of this command can result in a system hang and could require a system reboot.

   ---

4. Verify that the SCSI bus is disconnected.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 unavailable disconnected configured unknown c1::dsk/c1t3d0 unavailable disconnected configured unknown c1::dsk/c1t4d0 unavailable disconnected configured unknown

   The controller and all the devices that are attached to it are disconnected from the system.

SPARC: How to Connect a SCSI Controller

The following procedure uses SCSI controller c1 in the example of connecting a SCSI controller.

1. Become superuser.

2. Verify that the device is disconnected before you connect it.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 unavailable disconnected configured unknown c1::dsk/c1t3d0 unavailable disconnected configured unknown c1::dsk/c1t4d0 unavailable disconnected configured unknown

3. Connect the SCSI controller.

   # cfgadm -c connect c1

4. Verify that the SCSI controller is connected.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk connected configured unknown

SPARC: How to Add a SCSI Device to a SCSI Bus

SCSI controller c1 is used in the example of how to add a SCSI device to a SCSI bus.

When you add devices, you specify the Ap_Id of the SCSI HBA (controller) to which the device is attached, not the Ap_Id of the device itself.

1. Become superuser.

2. Identify the current SCSI configuration.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown

3. Add the SCSI device to the SCSI bus.

   1. Type the following cfgadm command.

      For example:

      # cfgadm -x insert_device c1 Adding device to SCSI HBA: /devices/sbus@1f,0/SUNW,fas@1,8800000 This operation will suspend activity on SCSI bus: c1

   2. Type y at the Continue (yes/no)? prompt to proceed.

      Continue (yes/no)? y SCSI bus quiesced successfully. It is now safe to proceed with hotplug operation.

      I/O activity on the SCSI bus is suspended while the hot-plug operation is in progress.

   3. Connect the device and then power it on.

   4. Type y at the Enter y if operation is complete or n to abort (yes/no)? prompt.

      Enter y if operation is complete or n to abort (yes/no)? y

4. Verify that the device has been added.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk connected configured unknown

   A new disk has been added to controller c1.

SPARC: How to Replace an Identical Device on a SCSI Controller

The following procedure uses SCSI disk c1t4d0 in the example of replacing an identical device on a SCSI controller.

1. Become superuser.

2. Identify the current SCSI configuration.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk connected configured unknown

3. Replace a device on the SCSI bus with another device of the same type.

   1. Type the following cfgadm command.

      For example:

      # cfgadm -x replace_device c1::dsk/c1t4d0 Replacing SCSI device: /devices/sbus@1f,0/SUNW,fas@1,8800000/sd@4,0 This operation will suspend activity on SCSI bus: c1

   2. Type y at the Continue (yes/no)? prompt to proceed.

      I/O activity on the SCSI bus is suspended while the hot-plug operation is in progress.

      Continue (yes/no)? y SCSI bus quiesced successfully. It is now safe to proceed with hotplug operation.

   3. Power off the device to be removed and remove it.

   4. Add the replacement device. Then, power it on.

      The replacement device should be of the same type and at the same address (target and lun) as the device to be removed.

   5. Type y at the Enter y if operation is complete or n to abort (yes/no)? prompt.

      Enter y if operation is complete or n to abort (yes/no)? y

4. Verify that the device has been replaced.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk connected configured unknown

SPARC: How to Remove a SCSI Device

The following procedure uses SCSI disk c1t4d0 in the example of removing a device on a SCSI controller.

1. Become superuser.

2. Identify the current SCSI configuration.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk connected configured unknown

3. Remove the SCSI device from the system.

   1. Type the following cfgadm command.

      For example:

      # cfgadm -x remove_device c1::dsk/c1t4d0 Removing SCSI device: /devices/sbus@1f,0/SUNW,fas@1,8800000/sd@4,0 This operation will suspend activity on SCSI bus: c1

   2. Type y at the Continue (yes/no)? prompt to proceed.

      Continue (yes/no)? y SCSI bus quiesced successfully. It is now safe to proceed with hotplug operation.

      I/O activity on the SCSI bus is suspended while the hot-plug operation is in progress.

   3. Power off the device to be removed and remove it.

   4. Type y at the Enter y if operation is complete or n to abort (yes/no)? prompt.

      Enter y if operation is complete or n to abort (yes/no)? y

   ---

   Note –

   This step must be performed if you are removing a SCSI RAID device from a SCSI RAID array.

   ---

4. Verify that the device has been removed from the system.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown

Troubleshooting SCSI Configuration Problems

This section provides error messages and possible solutions for troubleshooting SCSI configuration problems. For more information on troubleshooting SCSI configuration problems, see cfgadm(1M).

Error Message

cfgadm: Component system is busy, try again: failed to offline: device-path Resource Information ------------------ -------------------------- /dev/dsk/c1t0d0s0 mounted filesystem "/file-system"

Cause

You attempted to remove or replace a device with a mounted file system.

Solution

Unmount the file system that is listed in the error message and retry the cfgadm operation.

Error Message

cfgadm: Component system is busy, try again: failed to offline: device-path Resource Information ------------------ -------------------------- /dev/dsk/device-name swap area

Cause

If you use the cfgadm command to remove a system resource, such as a swap device or a dedicated dump device, a similar error message is displayed if the system resource is still active.

Solution

Unconfigure the swap areas on the device that is specified and retry the cfgadm operation.

Error Message

cfgadm: Component system is busy, try again: failed to offline: device-path Resource Information ------------------ -------------------------- /dev/dsk/device-name dump device (swap)

Cause

You attempted to remove or replace a dump device that is configured on a swap area.

Solution

Unconfigure the dump device that is configured on the swap area and retry the cfgadm operation.

Error Message

cfgadm: Component system is busy, try again: failed to offline: device-path Resource Information ------------------ -------------------------- /dev/dsk/device-name dump device (dedicated)

Cause

You attempted to remove or replace a dedicated dump device.

Solution

Unconfigure the dedicate dump device and retry the cfgadm operation.

How to Resolve a Failed SCSI Unconfigure Operation

Use this procedure if one or more target devices are busy and the SCSI unconfigure operation fails. Otherwise, future dynamic reconfiguration operations on this controller and target devices will fail with a dr in progress message.

1. Become superuser.

2. Reconfigure the controller.

   # cfgadm -c configure device-name

PCI or PCIe Hot-Plugging With the cfgadm Command (Task Map)

The following task map describes the tasks for managing PCI or PCIe devices on your system.

PCI or PCIe Hot-Plugging With the cfgadm Command

This section provides step-by-step instructions for hot-plugging PCI or PCIe adapter cards on SPARC and x86 systems.

In addition to the cfgadm command, the prtconf command is helpful during hot-plug operations. The prtconf command displays additional configuration information that pertains to the hardware.

After adding hardware, you can use the prtconf command to verify that the hardware is configured correctly. For example, after a configure operation, use the prtconf -D command to verify that the driver is attached to the newly installed hardware device. If the device driver has not been added to the system prior to hardware configuration, it may be manually added by using the add_drv command.

For more information, see prtconf(1M) and add_drv(1M).

In the examples, only PCI attachment points are listed, for brevity. The attachment points that are displayed on your system depend on your system configuration.

PCIe Led Indicator Behavior

You might observe the LED indicators on the system to get a visual indication about the status of the slot's hot-plug operation. The LED behavior, in case of PCI Express, matches that defined in the PCI Express specification or the behavior might otherwise be platform dependent.

Please refer to your platform guide for specific details. In case of PCI Express, when the Attention Button is pressed, the power indicator blinks, which indicates the beginning of a state transition. The blinking ends when the state transition has ended.

How to Display PCI Slot Configuration Information

This procedure has been updated to include PCIe configuration information.

The cfgadm command displays the status of PCI hot-pluggable devices and slots on a system. For more information, see cfgadm(1M).

1. Become superuser.

2. Display PCI configuration information.

   • Display PCI slot configuration information.

     For example:

     # cfgadm Ap_Id Type Receptacle Occupant Condition pci1:hpc0_slot0 unknown empty unconfigured unknown pci1:hpc0_slot1 unknown empty unconfigured unknown pci1:hpc0_slot2 unknown empty unconfigured unknown pci1:hpc0_slot3 ethernet/hp connected configured ok pci1:hpc0_slot4 unknown empty unconfigured unknown

   • Display specific PCI device information.

     For example:

     # cfgadm -s "cols=ap_id:type:info" pci Ap_Id Type Information pci1:hpc0_slot0 unknown Slot 7 pci1:hpc0_slot1 unknown Slot 8 pci1:hpc0_slot2 unknown Slot 9 pci1:hpc0_slot3 ethernet/hp Slot 10 pci1:hpc0_slot4 unknown Slot 11

     The logical Ap_Id, pci1:hpc0_slot0, is the logical Ap_Id for hot-pluggable slot, Slot 7. The component hpc0 indicates the hot-pluggable adapter card for this slot, and pci1 indicates the PCI bus instance. The Type field indicates the type of PCI adapter card that is present in the slot.

   • Display PCIe slot configuration information.

     For example:

     # cfgadm pci Ap_Id Type Receptacle Occupant Condition pcie1 unknown empty unconfigured unknown pcie2 unknown empty unconfigured unknown pcie3 unknown empty unconfigured unknown pcie4 etherne/hp connected configured ok pcie5 pci-pci/hp connected configured ok pcie6 unknown disconnected unconfigured unknown

   • Display specific PCIe device information.

     For example:

     # cfgadm -s "cols=ap_id:busy:o_state" pci Ap_Id Busy Occupant pcie1 n unconfigured pcie2 n unconfigured pcie3 n unconfigured pcie4 n configured pcie5 n configured pcie6 n configured

     ---

     Note –

     The logical Ap_Id in most cases should match the slot label that is silk-screened on the system chassis. Refer to your platform guide for the cfgadm output of the hot-pluggable slots. The Busy field can be displayed to ensure that the Ap_Id is not transitioning to another state before a hot-plug operation is attempted.

     ---

How to Remove a PCI Adapter Card

The following procedure has been updated for removing a PCIe adapter card. However, the procedure to remove an adapter card is the same whether you are using PCI or PCIe.

1. Become superuser.

2. Determine which slot the PCI adapter card is in.

   For example:

   # cfgadm pci Ap_Id Type Receptacle Occupant Condition pcie1 unknown empty unconfigured unknown pcie2 unknown empty unconfigured unknown pcie3 unknown empty unconfigured unknown pcie4 etherne/hp connected configured ok pcie5 pci-pci/hp connected configured ok pcie6 unknown disconnected unconfigured unknown

3. Stop the application that has the device open.

   For example, if the device is an Ethernet card, use the ifconfig command to bring down the interface and unplumb the interface.

4. Unconfigure the device manually by using the cfgadm(1M) command as shown below. Or, if you have a PCIe adapter card, use the auto-configuration method, such as pressing the slot's Attention Button as defined by your platform guide.

   # cfgadm -c unconfigure pcie4

5. Confirm that the device has been unconfigured.

   For example:

   # cfgadm pci Ap_Id Type Receptacle Occupant Condition pcie1 unknown empty unconfigured unknown pcie2 unknown empty unconfigured unknown pcie3 unknown empty unconfigured unknown pcie4 unknown connected unconfigured unknown pcie5 pci-pci/hp connected configured ok pcie6 unknown disconnected unconfigured unknown

   ---

   Note –

   The Type and Condition also become unknown when the device is unconfigured.

   ---

6. Disconnect the power to the slot manually. If the auto-configuration method is used, this step is not necessary. Refer to your platform guide for more information.

   # cfgadm -c disconnect pcie4

7. Confirm that the device has been disconnected.

   For example:

   # cfgadm pci Ap_Id Type Receptacle Occupant Condition pcie1 unknown empty unconfigured unknown pcie2 unknown empty unconfigured unknown pcie3 unknown empty unconfigured unknown pcie4 unknown disconnected unconfigured unknown pcie5 pci-pci/hp connected configured ok pcie6 unknown disconnected unconfigured unknown

8. Follow appropriate instructions in your platform guide to remove the PCI adapter card. After the card is removed, the Receptacle state is empty.

   For example:

   # cfgadm pci Ap_Id Type Receptacle Occupant Condition pcie1 unknown empty unconfigured unknown pcie2 unknown empty unconfigured unknown pcie3 unknown empty unconfigured unknown pcie4 unknown empty unconfigured unknown pcie5 pci-pci/hp connected configured ok pcie6 unknown disconnected unconfigured unknown

   ---

   Note –

   The auto-configuration method can be enabled or disabled at boot, depending on the platform implementation. Set the auto-configuration method as appropriate for your environment.

   ---

How to Add a PCI Adapter Card

The following procedure has been updated for adding a PCIe adapter card. However, the procedure to add an adapter card is the same whether you are using PCI or PCIe.

1. Become superuser.

2. Identify the hot-pluggable slot and open latches.

   For example, pcie3.

   # cfgadm pci Ap_Id Type Receptacle Occupant Condition pcie1 unknown empty unconfigured unknown pcie2 unknown empty unconfigured unknown pcie3 unknown empty unconfigured unknown pcie4 unknown empty unconfigured unknown pcie5 pci-pci/hp connected configured ok pcie6 unknown disconnected unconfigured unknown

3. Follow the appropriate instructions in your platform guide to insert a PCI adapter card into the slot.

4. Determine which slot the PCI adapter card is in after it is inserted.

   For example:

   # cfgadm pci Ap_Id Type Receptacle Occupant Condition pcie1 unknown empty unconfigured unknown pcie2 unknown empty unconfigured unknown pcie3 unknown disconnected unconfigured unknown pcie4 unknown empty unconfigured unknown pcie5 pci-pci/hp connected configured ok pcie6 unknown disconnected unconfigured unknown

5. Connect the power to the slot manually using the cfgadm command. Or, if you have a PCIe adapter card, use the auto-configuration method, such as pressing the slot's Attention Button as defined by your platform guide.

   For example:

   # cfgadm -c connect pcie3

6. Confirm that the attachment point is connected.

   For example:

   # cfgadm pci Ap_Id Type Receptacle Occupant Condition pcie1 unknown empty unconfigured unknown pcie2 unknown empty unconfigured unknown pcie3 unknown connected unconfigured unknown pcie4 unknown empty unconfigured unknown pcie5 pci-pci/hp connected configured ok pcie6 unknown disconnected unconfigured unknown

7. Configure the PCI adapter card manually by using the cfgadm command as shown below. If using the auto-configuration method, this step should not be necessary. Refer to your platform guide for more information.

   For example:

   # cfgadm -c configure pcie3

8. Verify the configuration of the PCI adapter card in the slot.

   For example:

   # cfgadm pci Ap_Id Type Receptacle Occupant Condition pcie1 unknown empty unconfigured unknown pcie2 unknown empty unconfigured unknown pcie3 etherne/hp connected configured unknown pcie5 pci-pci/hp connected configured ok pcie6 unknown disconnected unconfigured unknown

9. Configure any supporting software if this device is a new device.

   For example, if this device is an Ethernet card, use the ifconfig command to set up the interface.

   ---

   Note –

   The auto-configuration method can be enabled or disabled at boot, depending on the platform implementation. Set the auto-configuration method as appropriate for your environment.

   ---

Troubleshooting PCI Configuration Problems

Error Message

cfgadm: Configuration operation invalid: invalid transition

Cause

An invalid transition was attempted.

Solution

Check whether the cfgadm -c command was issued appropriately. Use the cfgadm command to check the current receptacle and occupant state and to make sure that the Ap_Id is correct.

Error Message

cfgadm: Attachment point not found

Cause

The specified attachment point was not found.

Solution

Check whether the attachment point is correct. Use the cfgadm command to display a list of available attachment points. Also check the physical path to see if the attachment point is still there.

Reconfiguration Coordination Manager (RCM) Script Overview

The Reconfiguration Coordination Manager (RCM) is the framework that manages the dynamic removal of system components. By using RCM, you can register and release system resources in an orderly manner.

You can use the new RCM script feature to write your own scripts to shut down your applications, or to cleanly release the devices from your applications during dynamic reconfiguration. The RCM framework launches a script automatically in response to a reconfiguration request, if the request impacts the resources that are registered by the script.

You can also release resources from applications manually before you dynamically remove the resource. Or, you can use the cfgadm command with the -f option to force a reconfiguration operation. However, this option might leave your applications in an unknown state. Also, the manual release of resources from applications commonly causes errors.

The RCM script feature simplifies and better controls the dynamic reconfiguration process. By creating an RCM script, you can do the following:

• Automatically release a device when you dynamically remove a device. This process also closes the device if the device is opened by an application.

• Run site-specific tasks when you dynamically remove a device from the system.

What Is an RCM Script?

• An executable shell script (Perl, sh, csh, or ksh) or binary program that the RCM daemon runs. Perl is the recommended language.

• A script that runs in its own address space by using the user ID of the script file owner.

• A script that is run by the RCM daemon when you use the cfgadm command to dynamically reconfigure a system resource.

What Can an RCM Script Do?

You can use an RCM script to release a device from an application when you dynamically remove a device. If the device is currently open, the RCM script also closes the device.

For example, an RCM script for a tape backup application can inform the tape backup application to close the tape drive or shut down the tape backup application.

How Does the RCM Script Process Work?

You can invoke an RCM script as follows:

$ script-name command [args ...]

An RCM script performs the following basic steps:

1. Takes the RCM command from command-line arguments.

2. Executes the command.

3. Writes the results to stdout as name-value pairs.

4. Exits with the appropriate exit status.

The RCM daemon runs one instance of a script at a time. For example, if a script is running, the RCM daemon does not run the same script until the first script exits.

RCM Script Commands

You must include the following RCM commands in an RCM script:

• scriptinfo – Gathers script information

• register – Registers interest in resources

• resourceinfo – Gathers resource information

You might include some or all of the following RCM commands:

• queryremove – Queries whether the resource can be released

• preremove – Releases the resource

• postremove – Provides post-resource removal notification

• undoremove – Undoes the actions done in preremove

For a complete description of these RCM commands, see rcmscript(4).

RCM Script Processing Environment

When you dynamically remove a device, the RCM daemon runs the following:

• The script's register command to gather the list of resources (device names) that are identified in the script.

• The script's queryremove and preremove commands prior to removing the resource if the script's registered resources are affected by the dynamic remove operation.

• The script's postremove command if the remove operation succeeds. However, if the remove operation fails, the RCM daemon runs the script's undoremove command.

RCM Script Tasks

The following sections describe the RCM script tasks for application developers and system administrators.

Application Developer RCM Script (Task Map)

The following task map describes the tasks for an application developer who is creating an RCM script.

System Administrator RCM Script (Task Map)

The following task map describes the tasks for a system administrator who is creating an RCM script to do site customization.

Naming an RCM Script

A script must be named as vendor,service where the following applies:

vendor

Is the stock symbol of the vendor that provides the script, or any distinct name that identifies the vendor.

service

Is the name of the service that the script represents.

Installing or Removing an RCM Script

You must be superuser (root) to install or remove an RCM script. Use this table to determine where you should install your RCM script.

How to Install an RCM Script

1. Become superuser.

2. Copy the script to the appropriate directory.

   See Table 6–1.

   For example:

   # cp SUNW,sample.pl /usr/lib/rcm/scripts

3. Change the user ID and the group ID of the script to the desired values.

   # chown user:group /usr/lib/rcm/scripts/SUNW,sample.pl

4. Send SIGHUP to the RCM daemon.

   # pkill -HUP -x -u root rcm_daemon

How to Remove an RCM Script

1. Become superuser.

2. Remove the script from the RCM script directory.

   For example:

   # rm /usr/lib/rcm/scripts/SUNW,sample.pl

3. Send SIGHUP to the RCM daemon.

   # pkill -HUP -x -u root rcm_daemon

How to Test an RCM Script

1. Set environment variables, such as RCM_ENV_FORCE, in the command-line shell before running your script.

   For example, in the Korn shell, use the following:

   $ export RCM_ENV_FORCE=TRUE

2. Test the script by running the script commands manually from the command line.

   For example:

   $ script-name scriptinfo $ script-name register $ script-name preremove resource-name $ script-name postremove resource-name

3. Make sure that each RCM script command in your script prints appropriate output to stdout.

4. Install the script in the appropriate script directory.

   For more information, see How to Install an RCM Script.

5. Test the script by initiating a dynamic remove operation.

   For example, assume your script registers the device, /dev/dsk/c1t0d0s0. Try these commands.

   $ cfgadm -c unconfigure c1::dsk/c1t0d0 $ cfgadm -f -c unconfigure c1::dsk/c1t0d0 $ cfgadm -c configure c1::dsk/c1t0d0

   ---

   Caution –

   Make sure that you are familiar with these commands because they can alter the state of the system and cause system failures.

   ---

Tape Backup RCM Script Example

This example illustrates how to use an RCM script for tape backups.

What the Tape Backup RCM Script Does

The tape backup RCM script performs the following steps:

1. Sets up a dispatch table of RCM commands.

2. Calls the dispatch routine that corresponds to the specified RCM command and exits with status 2 for unimplemented RCM commands.

3. Sets up the scriptinfo section.

   rcm_script_func_info=Tape backup appl script for DR

4. Registers all tape drives in the system by printing all tape drive device names to stdout.

   rcm_resource_name=/dev/rmt/$f

   If an error occurs, the script prints the error information to stdout.

   rcm_failure_reason=$errmsg

5. Sets up the resource information for the tape device.

   rcm_resource_usage_info=Backup Tape Unit Number $unit

6. Sets up the preremove information by checking if the backup application is using the device. If the backup application is not using the device, the dynamic reconfiguration operation continues. If the backup application is using the device, the script checks RCM_ENV_FORCE. If RCM_ENV_FORCE is set to FALSE, the script denies the dynamic reconfiguration operation and prints the following message:

   rcm_failure_reason=tape backup in progress pid=...

   If RCM_ENV_FORCE is set to TRUE, the backup application is stopped, and the reconfiguration operation proceeds.

Outcomes of the Tape Backup Reconfiguration Scenarios

Here are the various outcomes if you use the cfgadm command to remove a tape device without the RCM script.

• If you use the cfgadm command and the backup application is not using the tape device, the operation succeeds.

• If you use the cfgadm command and the backup application is using the tape device, the operation fails.

Here are the various outcomes if you use the cfgadm command to remove a tape device with the RCM script.

• If you use the cfgadm command and the backup application is not using the tape device, the operation succeeds.

• If you use the cfgadm command without the -f option and the backup application is using the tape device, the operation fails with an error message similar to the following:

  tape backup in progress pid=...

• If you use the cfgadm -f command and the backup application is using the tape device, the script stops the backup application and the cfgadm operation succeeds.

Example—Tape Backup RCM Script

#! /usr/bin/perl -w
   #
   # A sample site customization RCM script.
   #
   # When RCM_ENV_FORCE is FALSE this script indicates to RCM that it cannot
   # release the tape drive when the tape drive is being used for backup.
   #
   # When RCM_ENV_FORCE is TRUE this script allows DR removing a tape drive
   # when the tape drive is being used for backup by killing the tape
   # backup application.
   #
    
    use strict;
    
    my ($cmd, %dispatch);
    $cmd = shift(@ARGV);
# dispatch table for RCM commands
    %dispatch = (
            "scriptinfo"    =>      \&do_scriptinfo,
            "register"      =>      \&do_register,
            "resourceinfo"  =>      \&do_resourceinfo,
            "queryremove"   =>      \&do_preremove,
            "preremove"     =>      \&do_preremove
    );
    
    
    if (defined($dispatch{$cmd})) {
            &{$dispatch{$cmd}};
    } else {
            exit (2);
    }
    
    sub do_scriptinfo
    {
            print "rcm_script_version=1\n";
            print "rcm_script_func_info=Tape backup appl script for DR\n";
            exit (0);
    }
    
    sub do_register
{
            my ($dir, $f, $errmsg);
    
            $dir = opendir(RMT, "/dev/rmt");
            if (!$dir) {
                 $errmsg = "Unable to open /dev/rmt directory: $!";
                 print "rcm_failure_reason=$errmsg\n";
                 exit (1);
            }
    
            while ($f = readdir(RMT)) {
                # ignore hidden files and multiple names for the same device
                if (($f !~ /^\./) && ($f =~ /^[0-9]+$/)) {
                        print "rcm_resource_name=/dev/rmt/$f\n";
                    }
                    
            }
    
            closedir(RMT);
            exit (0);
    }
sub do_resourceinfo
    {
      my ($rsrc, $unit);
    
      $rsrc = shift(@ARGV);
      if ($rsrc =~ /^\/dev\/rmt\/([0-9]+)$/) {
           $unit = $1;
           print "rcm_resource_usage_info=Backup Tape Unit Number $unit\n";
           exit (0);
       } else {
           print "rcm_failure_reason=Unknown tape device!\n";
            exit (1);
        }
    }
    
    sub do_preremove
    {
            my ($rsrc);
    
            $rsrc = shift(@ARGV);
    
            # check if backup application is using this resource
            #if (the backup application is not running on $rsrc) {
                    # allow the DR to continue
            #        exit (0);
            #}
            #
            # If RCM_ENV_FORCE is FALSE deny the operation.
            # If RCM_ENV_FORCE is TRUE kill the backup application in order
            # to allow the DR operation to proceed
            #
            if ($ENV{RCM_ENV_FORCE} eq 'TRUE') {
                 if ($cmd eq 'preremove') {
                         # kill the tape backup application
                 }
                 exit (0);
            } else {
               #
               # indicate that the tape drive can not be released
               # since the device is being used for backup by the
               # tape backup application
               #
               print "rcm_failure_reason=tape backup in progress pid=...\n"
;
               exit (3);
            }
    }