PCI Hot Plug User's Guide 2.5.1

4.1 cfgadm (cfgadm_pci(1M))

NAME

cfgadm - PCI Hot Plug operation

SYNOPSYS

/usr/sbin/cfgadm [-v] [ap_id | -s "select=class(pci)"]

/usr/sbin/cfgadm -c [disconnect | configure] ap_id [ap_id...]

/usr/sbin/cfgadm -x led[=fault,mode=[on | off | blink]] ap_id [ap_id*]

/usr/sbin/cfgadm -x [enable_autoconfig | disable_autoconfig] ap_id [ap_id...]

AVAILABILITY

• The user must be a super user to execute this command.
  For requirements of this command, please refer to "1.2 PCI Hot Plug Requirements".

DESCRIPTION

This command provides the PCI Hot Plug feature. The features include power on/off the PCI slots and configure/disconnect the PCI devices.
The command must be executed from the system partition where the PCI slots are located.

OPTIONS

The cfgadm command has the following options.

"ap_id" represents the PCI card's logical ID displayed by cfgadm.

• Options for display slot status information

No option

Lists information for all PCI slots.
Type, Receptacle, Occupant and Condition are displayed for each PCI slot.

Type

Shows types of PCI slots. PCI slots displayed as type "*/hp" are PCI Hot Plug supported PCI slots.

Receptacle

Shows connection status of PCI slots. There are three kinds of status, disconnected (power off), connected (power on) and empty (no card is inserted).

Occupant

Shows occupancy status of PCI slots. There are two kinds of status, configured (PCI device is configured) and unconfigured (not yet configured).

Condition

Shows failure status of PCI slots. There are four kinds of status, ok (normal), failed (had failure), unknown (not yet evaluated) and unusable (disabled).

ap_id*

Shows status of a PCI slot specified with ap_id.
There are three formats of ap_id according to the Solaris OS versions.

1. Solaris 8 OS and Solaris 9 OS

   
   pcipsyX:CYM0Z-PCI#slotWW (slots in cabinet)

   WW represents physical slot number, X represents PCI Bus nexus driver instance number, Y represents cabinet number(0,1) and Z represents internal number of system boards(0,1,2,3).

   pcipsyX:RYB0Z-PCI#slotWW (slots in PCI/ disk box)

   WW represents physical slot number, X represents PCI Bus nexus driver instance number, Y represents I/O cabinet number (0,1,2,3) and Z represents PCI/ disk box number (0,1,2,3,4,5,6,7).

   pcipsyX:PCI#slotWW

   WW represents physical slot number, X represents PCI Bus nexus driver instance number.

2. Solaris 10 OS

   
   CYM0Z-PCI#WW (slots in cabinet)

   WW represents physical slot number, Y represents cabinet number(0,1) and Z represents internal number of system boards(0,1,2,3).

   RYB0Z-PCI#WW (slots in PCI/ disk box)

   WW represents physical slot number, Y represents I/O cabinet number (0,1,2,3) and Z represents PCI/ disk box number (0,1,2,3,4,5,6,7).

   PCI#WW

   WW represents physical slot number.

-s "select=class(pci)"

Show status of PCI cards only.

-v

Execute in verbose mode.

• Options for PCI Hot Plug operations

-c function

The following functions are used for PCI Hot Plug operations.

disconnect

Unconfigure and power off a PCI slot specified with ap_id.
This option is specified to complete detaching the PCI slot.

configure

Power on and configure a PCI device specified with ap_id.
This option is specified to configure or hotswap the PCI slot.

-x led[=[led],mode=[mode]]

If "=[led],mode=[mode]" is not specified, prints the LED status of the PCI slot with ap_id. fault LED corresponds to ALARM LED and active LED corresponds to ONLINE LED. power LED and attn LED are not supported and the statuses are shown as "unknown".
If "=[led],mode=[mode]" is specified, sets the mode of the specified LED on the PCI slot with the designated ap_id.

• The following arguments are used for led.
  fault: ALARM LED
• The following arguments are used for mode.
  on: Indicates LED light on.
  blink: Indicates LED light blinking.
  off: Indicates LED light off.
  

-x function

The following functions are used for PCI Hot Plug operations. PCI Hot Plug operation using each pushbutton can be enabled/disabled with this command. It is highly recommended to disable the PCI Hot Plug feature on the PCI cards to avoid miss operations when the PCI cards are used. When PCI cards need to be removed or exchanged, the functions can be enabled.

enable_autoconfig

Set autoconfig feature for a PCI device specified with ap_id. With this option, per-slot pushbuttons can perform either of the following operations.
- Power on and configure the PCI device with ap_id.
- Unconfigure and power off the PCI device with ap_id.
This option is specified to prepare to use PCI Hot Plug feature with pushbutton on the PCI slot.
Default is enabled.

disable_autoconfig

Disables autoconfig feature for a PCI device specified with ap_id. The pushbutton of the PCI slot cannot perform power on/off or configure/unconfigure operations after this command is executed.

EXAMPLES

1. Solaris 8 OS and Solaris 9 OS

• Print status of all PCI slots.
  # cfgadm
  This command prints as follows:
  

• View the detail information of PCI slot specified with ap_id pcipsy2:R0B00-PCI#slot01.
  # cfgadm -v pcipsy2:R0B00-PCI#slot01
  This command prints as follows:
  

• Power on and configure a PCI slot specified with ap_id pcipsy2:R0B00-PCI#slot01. The PCI slot is described as:
  Physical slot number 01, PCI Bus nexus driver instance number 2, cabinet number is 0 and I./O box number is 00.
  # cfgadm -c configure pcipsy2:R0B00-PCI#slot01
  
• Confirms the mode of the LEDs on a PCI device specified with ap_id pcipsy2:R0B00-PCI#slot01.
  # cfgadm -x led pcipsy2:R0B00-PCI#slot01
  This command prints as follows:
  

• Let the ALARM LED blink on the PCI slot with ap_id pcipsy2:R0B00-PCI#slot01. Then confirm the location of PCI slot to be disconnected.
  # cfgadm -x led=fault,mode=blink pcipsy2:R0B00-PCI#slot01
  
• Unconfigure and power off the PCI slot with ap_id pcipsy2:R0B00-PCI#slot01.
  # cfgadm -c disconnect pcipsy2:R0B00-PCI#slot01
  

2. Solaris 10 OS

• Print status of all PCI slots.
  # cfgadm
  This command prints as follows:
  

• View the detail information of PCI slot specified with ap_id R0B00-PCI#01.
  # cfgadm -v R0B00-PCI#01
  This command prints as follows:
  

• Power on and configure a PCI slot specified with ap_id R0B00-PCI#01. The PCI slot is described as:
  Physical slot number 01, cabinet number is 0 and I/O box number is 00.
  # cfgadm -c configure R0B00-PCI#01
  
• Confirms the mode of the LEDs on a PCI device specified with ap_id R0B00-PCI#01.
  # cfgadm -x led R0B00-PCI#01
  This command prints as follows:
  

• Let the ALARM LED blink on the PCI slot with ap_id R0B00-PCI#01. Then confirm the location of PCI slot to be disconnected.
  # cfgadm -x led=fault,mode=blink R0B00-PCI#01
  
• Unconfigure and power off the PCI slot with ap_id R0B00-PCI#01.
  # cfgadm -c disconnect R0B00-PCI#01

EXIT STATUS

This command returns the following values.

0: display information successfully

>0: An error occurred.

Please refer to console messages in "5.1 Command line Messages"

SEE ALSO

cfgadm(1M)

NOTES

• Please confirm the PCI card to be disconnected/connected is available for PCI Hot Plug operation using cfgadm (cfgadm_pci(1M)) with no option.
• Before disconnecting a file related device, be sure that the I/O device is not busy. For more information, refer to "PCI Hot Plug User's Guide I/O device edition"
• To insert or remove PCI cards, the READY LED must be off. If it is on, the operation may cause hardware failures.
• The connect and unconfigure functions for the -c option should not be used
• The enable_slot and disable_slot functions for the -x option are not used.
• If the status of a LED is changed using -x led option, the LED might not show the correct status. Blinking the ALARM LED to locate the target slot as follows should not have any problems.
  # cfgadm -x led=fault,mode=blink ap_id
• When a failure on a PCI card occurs and the condition of the slot is detected as 'failed', the slot is not usable. Do not attempt to operate PCI Hot Plug on a slot indicating a 'failed' condition.
• Printing status using cfgadm (cfgadm_pci(1M)) might take long time when the device configuration process devfsadmd (1M) is running. devfsadmd (1M) is responsible for device reconfiguration at boot time or dynamic reconfiguration. While devfsadmd (1M) updates the device information, the necessary information for cfgadm is locked by devfsadm. Therefore, cfgadm (1M) needs to wait until the device reconfiguration is finished.
  If the system has many device modifications, or it is the first time to configure the device information, reconfiguration of device information takes long time. After the device configuration is finished, the cfgadm(cfgadm_pci(1M)) commands will respond promptly.

EXAMPLE ERROR MESSAGES

This command sometimes fails because of syntax error or other reasons.

The followings are example error messages that are most likely to occur.

Error messages of usual PCI Hot Plug operations

• When an invalid ap_id is specified.

  Message	cfgadm: Attachment point not found
  Cause	Specified ap_id is invalid.
  Remedy	Confirm the correct ap_id using cfgadm (cfgadm_pci(1M)) and try again.

• When specified state transition is not executable.

  Message	cfgadm: Configuration operation invalid: invalid transition
  Cause	Specified state transition is not executable.
  Remedy	Confirm the available transition and try again.

• When specified arguments are invalid. (LED operations, etc.)

  Message	cfgadm: Configuration operation invalid
  Cause	Specified arguments are invalid.
  Remedy	Confirm the valid arguments and try again.

• When configure operation is invoked for empty PCI slot.

  Message	cfgadm: Hardware specific failure: configure failed
  Cause	Configure operation is invoked for empty PCI slot. Note: This error occurs because the specified PCI Hot Plug operation is not executable. The error message "hardware specific failure" is different from the cause of the error.
  Remedy	Confirm the correct ap_id and try again.