cfgadm_shp man page on SunOS

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
SunOS logo
[printable version]

cfgadm_shp(1M)		System Administration Commands		cfgadm_shp(1M)

NAME
       cfgadm_shp  -  PCI  Express  and Standard PCI Hotplug hardware-specific
       commands for cfgadm

SYNOPSIS
       /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]

DESCRIPTION
       The PCI Express and Standard  PCI  Hotplug  hardware-specific  library,
       /usr/lib/cfgadm/shp.so.1,  provides support for hotplugging PCI Express
       and Standard PCI Hotplug adapter cards into the respective hotpluggable
       slots  in  a system that is hotplug-capable, through the cfgadm command
       (see cfgadm(1M)). Support for the rest PCI Hotplug adapter cards (other
       than  PCI  Express  and	Standard  PCI  Hotplug	cards) are provided by
       cfgadm_pci library (see cfgadm_pci(1M)). Hotplug administrative	models
       between	PCI  Express  Hotplug and Standard PCI Hotplug remain the same
       except where noted in this man page.

       For PCI hotplug, each hotplug slot on a specific PCI bus is represented
       by an attachment point of that PCI bus.

       An attachment point consist of two parts: a receptacle and an occupant.
       The receptacle under PCI hotplug is usually referred to as the physical
       hot  pluggable slot; and the occupant is usually referred to as the PCI
       adapter card that plugs into the slot.

       Attachment points are named through ap_ids.  There  are	two  types  of
       ap_ids: logical and physical. The physical ap_id is based on the physi‐
       cal pathname, for example:

	 /devices/pci@7c,0/pci10de,5d@d:pcie2

       Whereas the logical ap_id is a shorter, more  user-friendly  name,  for
       example, pcie2. The ap_type for Hotplug PCI is pci.

       Note  that  the	ap_type is not the same as the information in the Type
       field.

   PCI Express ap_id Naming
       For attachment points located in a PCI Express hierarchy (that  is, the
       parent  or  an ancestor is a PCI Express device),  including attachment
       points that are not PCI Express devices themselves, the	naming	scheme
       shown below is used.

       Grammar:

       APID : absolute-slot-path

	   Fundamental term.

       absolute-slot-path : slot-path[:slot-path[:slotpath ...]]

	   ...where  fru-id  indicates the chassis FRU, if any, containing the
	   slot-id.

       fru-id : fru-type[serialid#]

	   ...where fru-type is "iob" for a  PCI  Express  expansion  chassis,
	   followed by its serial number serialid#, if available

       slot-id : slot-name | device-type physical-slot# | \
       nexus-driver-name nexus-driver-instance.\
       device-type pci-device-number

	   ...where  slot-name	is a name assigned by the platform or hardware
	   itself. device-type is either pcie for PCI Express devices  or  pci
	   for	PCI  devices.  nexus-driver-name  is  the  driver name for the
	   device component; physical-slot# is the hardware slot  number;  and
	   pci-device-number  is the PCI  device number in standard PCI nomen‐
	   clature.

       First, an absolute-slot-path is constructed that attempts  to  describe
       the  attachment point's topological location in more physically identi‐
       fiable terms for the user. This absolute-slot-path  consists  of	 slot-
       path  components	 each  separated  by a : (colon). The leaf or leftmost
       slot-path component  describes  the  device  of	the  attachment	 point
       itself,	while  its right-adjacent slot-path component up to the right‐
       most or topmost slot-path component describes the parent up to the root
       devices, respectively.

       Each  slot-path	consists of a slot-id optionally preceded by a fru-id,
       which identifies an expansion chassis containing the  device  described
       by slot-id (detailed below). fru-id consists of fru-type followed by an
       optional serialid#. fru-type is "iob" for PCI Express expansion chassis
       types, while serialid# is either a 64-bit hexadecimal number indicating
       a raw serial number obtained from the expansion chassis hardware, or an
       upper-case,  ASCII  four-character sequence for a Sun-branded expansion
       chassis.

       Each slot-id consists of one of three possible forms:

       slot-id form (1)

	   slot-names

       slot-id form (2)

	   device-type physical-slot#

       slot-id form (3)

	   nexus-driver-name  nexus-driver-instance   device-type  pci-device-
	   number

       The  precedence of which form to select flows from the lowest form num‐
       ber to the highest form number, or from	top  to	 bottom	 as  described
       above.  If  a  form  cannot  be successfully constructed, then the next
       numerically higher form is attempted.

       The slot-names in slot-id form (1) is taken from the  slot-names	 prop‐
       erty  of	 the  corresponding  node  in  the   evice  tree and is a name
       assigned by hardware or the platform. This format is not predefined  or
       established.

       In  slot-id form (2), device-type indicates the device type of the com‐
       ponent's slot, and is either pcie for PCI Express or pci for PCI, while
       physical-slot#,	taken  from  the physical-slot# property of its corre‐
       sponding device node, indicates the hardware slot number of the	compo‐
       nent.

       slot-id	form  (3)  is used when all other forms cannot be successfully
       constructed, and is considered to be the	 default  form.	 nexus-driver-
       name  is	 the  component's  driver  name; nexus-driver-instance is this
       driver's instance; device-type is the same as described	in  form  (2);
       pci-device-number  is  the  PCI device number as described and used for
       device configuration cycles in standard PCI nomenclature.

       In summary of the slot-path component, expanding the optional FRU  com‐
       ponent that might precede it, slot-path will consist one of the follow‐
       ing forms in order:

       (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

       Lastly, the final form of the actual  ap_id  name  used	in  cfgadm  is
       decided as follows, specified in order of precedence:

       ap_id form (1)

	   If  the absolute-slot-path can fit within the fixed length limit of
	   cfgadm's ap_id field, then absolute-slot-path itself is used

       ap_id form (2)

	   (absolute-slot-path exceeds the ap_id length	 limit)	 If  the  last
	   slot_path  component	 is contained within an expansion chassis, and
	   it contains a serialid#, then the last slot_path component is used.
	   The	requirement  for a serialid# in this form is to ensure a glob‐
	   ally unique ap_id.

       ap_id form (3)

	   (absolute-slot-path exceeds the ap_id  length  limit)  The  default
	   form, slot-id form (3), of the last slot_path component is used.

       Whichever final ap_id name is used, the absolute-slot-path is stored in
       the Information (info) field which can be displayed using the -s or  -v
       options.	 This  information can be used to physically locate any ap_ids
       named using ap_id form (2) or ap_id form (3). The absolute-slot-path is
       transformed  slightly  when  stored  in	the  information field, by the
       replacement of a colon (:) with forward slashes (/)   to	 more  closely
       denote a topological context. The  absolute-slot-path can include slot-
       path components that are not hotpluggable above the leaf	 or  rightmost
       slot-path component up to the onboard host slot.

       See the Examples section for a list of hotpluggable examples.

OPTIONS
       The following options are supported:

       -c function

	   The following functions are supported for PCI hotpluggable slots:

	   configure

	       Configure the PCI device in the slot to be used by Solaris.

	   connect

	       Connect the slot to PCI bus.

	   disconnect

	       Disconnect the slot from the PCI bus.

	   insert

	       Not supported.

	   remove

	       Not supported.

	   unconfigure

	       Logically remove the PCI device's resources from the system.

       -f

	   Not supported.

       -h ap_id | ap_type

	   Display PCI hotplug-specific help message.

       -l list

	   List the values of PCI Hot Plug slots.

       -o hardware_options

	   No hardware specific options are currently defined.

       -s listing_options

	   Same as the generic cfgadm(1M).

       -t ap_id

	   This	 command  is  only supported on platforms that support testing
	   capability on the slot.

       -v

	   Execute in verbose mode.

	   When the -v option is used with the -l option, the  cfgadm  command
	   outputs  information	 about	the  attachment	 point. For attachment
	   points located in a PCI Express hierarchy,  the  Information	 field
	   will	 contain  the  attachment point's absolute slot path location,
	   including any hardware- or platform-specific	 labeling  information
	   for	each  component	 in  the slot path. Each component in the slot
	   path will be separated by a / (forward  slash).  See	 "PCI  Express
	   ap_id  Naming,"  above.  For	 PCI  Hot  Plug	 attachment points not
	   located in a PCI Express hierarchy, see cfgadm_pci(1M). The	infor‐
	   mation  in the Type field is printed with or without the -v option.
	   The occupant Type field will describe the  contents	of  the	 slot.
	   There are two possible values:

	   unknown

	       The  slot  is  empty. If a card is in the slot, the card is not
	       configured or there is no driver for the device on the card.

	   subclass/board

	       The card in the slot is either a single-function or multi-func‐
	       tion device.

	       subclass	 is  a	string	representing  the subclass code of the
	       device, for example, SCSI, ethernet, pci-isa, and so forth.  If
	       the card is a multi-functional device,  MULT will get displayed
	       instead.

	       board is a string representing the board type  of  the  device.
	       For example, hp is the string used for a PCI Hot Plug adapter.

       -x hardware_function

	   Perform  hardware-specific function. These hardware-specific	 func‐
	   tions should not normally change the state of a receptacle or occu‐
	   pant.

	   The following hardware_function is supported:

	   led=[led_sub_arg],mode=[mode_sub_arg]

	       Without	subarguments,  display	a list of the current LED set‐
	       tings. With subarguments, set the mode of a specific LED for  a
	       slot.

	       Specify led_sub_arg as fault, power, attn, or active.

	       Specify mode_sub_arg as on, off, or blink.

	       For  PCI	 Express,  only	 the power and attn LEDs are valid and
	       only the state of the attn LED can be changed.

	       Changing the state of the LED does not change the state of  the
	       receptacle  or  occupant.  Normally, the LEDs are controlled by
	       the hotplug controller, no user intervention is necessary.  Use
	       this command for testing purposes.

	       Caution -

		 Changing  the	state of the LED can misrepresent the state of
		 occupant or receptacle.
	       The following command displays the values of LEDs:

		 example# cfgadm -x led pcie2
		 Ap_Id		   Led
		 pcie2	   power=on,fault=off,active=off,attn=off

	       The following command sets the attn LED to  blink  to  indicate
	       the location of the slot:

		 example# cfgadm -x led=attn,mode=blink pcie2

EXAMPLES
       Example 1 Displaying the Value of Each Slot

       The following command displays the values of each slot:

	 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

       Example 2 Replacing a Card

       The following command lists all DR-capable attachment points:

	 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

       The  following  command	unconfigures  and electrically disconnects the
       card  identified by pcie7:

	 example# cfgadm -c disconnect pcie7

       The change can be verified by entering the following command:

	 example# cfgadm pcie7
	 Ap_Id	   Type		Receptacle   Occupant	  Condition
	 pcie7	   unknown	disconnected unconfigured unknown

       At this point the card can be swapped. The following  command  electri‐
       cally connects and configures the replacement card:

	 example# cfgadm -c configure pcie7

       The change can be verified by entering the following command:

	 example# cfgadm pcie7
	 Ap_Id	   Type		Receptacle   Occupant	  Condition
	 pcie7	   etherne/hp	connected    configured	  ok

       Example 3 Interpreting ApIds in a PCI Express Topology

       The  following  command	shows  a  listing for a topology with both PCI
       Express and PCI attachment points in an I/O expansion chassis connected
       to hotpluggable slots at the host level:

	 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

       In  this	 example,  the	iou#0-pci#[0-3] entries represents the topmost
       hotpluggable slots in the system. Because the   iou#n-pci#n  form  does
       not  match any of the forms stated in the grammar specification section
       described above, we can infer that such a name for the  base  component
       in  this	  hotplug  topology  is	 derived from the platform through the
       slot-names property.

       The slots in the preceding output are described as follows:

       Slot iou#0-pci#0

	   This slot is empty or its occupant is unconfigured.

       Slot iou#0-pci#1

	   This slot contains an  expansion  chassis  with  two	  hotpluggable
	   slots,  pci3	 and  pci4. pci3 and pci4 represent two PCI slots con‐
	   tained within that expansion chassis with physical slot  numbers  3
	   and	4,  respectively.  The expansion chassis in this case does not
	   have or export a serial-id.

       Slot iou#0-pci#2

	   This slot contains a third-party expansion chassis with a hexadeci‐
	   mal	serial-id of 58071. Within that expansion chassis are two hot‐
	   pluggable slots, pcie1 and special.	pcie1 represents a PCI Express
	   slot	 with  physical	 slot  number  1. The slot special has a label
	   which is derived from the platform, hardware, or firmware.

       Slot iou#0-pci#3

	   This slot contains a Sun expansion chassis with an  FRU  identifier
	   of  BADF.  This expansion chassis contains three PCI Express slots,
	   pcie1, pcie2, and pcie3 with physical slot numbers  1,  2,  and  3,
	   respectively;  and two PCI slots, pci1 and pci2, with physical slot
	   numbers 1 and 2, respectively.

       The following command shows a listing for  a  topology  with  both  PCI
       Express and PCI attachment points in an I/O expansion chassis with con‐
       nected hotpluggable and non-hotpluggable host slots:

	 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

       In this example, the host system only has one hotpluggable slot, Slot1.
       We  can	infer  that Slot2 and Slot5 are not hotpluggable slots because
       they do not appear as attachment points themselves in cfgadm.  However,
       Slot2 and Slot5 each contains a third party expansion chassis with hot‐
       pluggable slots.

       The following command shows a listing for a  topology  with  attachment
       points that are lacking in certain device properties:

	 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

       In  this	 example,  the	host  system  contains two hotpluggable slots,
       px_pci7.pcie0 and px_pci11.pcie0. In this case, it  uses	 slot-id  form
       (3)  (  the default form) for the base slot-path component in the abso‐
       lute-slot-path, because the framework could not obtain enough  informa‐
       tion to produce other more descriptive forms of higher precedence.

       Interpreting right-to-left, attachment point px_pci7.pcie0 represents a
       PCI Express slot with PCIdevice number 0 (which does not imply a physi‐
       cal  slot number of the same number), bound  to	nexus  driver  px_pci,
       instance 7. Likewise, attachment point px_pci11.pcie0 represents a  PCI
       Express	slot  with  PCI device number 0 bound to driver instance 11 of
       px_pci.

       Under px_pci11.pcie0 is	a  third-party	expansion  chassis  without  a
       serial-id and with three hotpluggable PCI Express slots.

       The  following  command	shows a listing for a topology with attachment
       point paths exceeding the ApId field length limit:

	 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

       In this example, there is only one  hotpluggable	 slot,	pcie4  in  the
       host.  Connected under pcie4 is a Sun  expansion chassis with FRU iden‐
       tifier SUNW. Nested under PCI Express  slot  pcie2  of  that  expansion
       chassis	(ApId pcie4:iobSUNW.pcie2) lies another expansion chassis with
       three hotpluggable PCI slots.

       Because the length of the absolute-slot-path form of:

	 pcie4/iobSUNW.pcie2/iob8879c3f3.pci1...3

       ...exceeds the ApId field length limit, and the leaf  slot-path	compo‐
       nent  is	 globally unique, ap_id form (2) is used, where the leaf slot-
       path component in the absolute-slot-path is used as the final ApId.

       The following command shows a listing for a  topology  with  attachment
       point  paths  exceeding	the ApId field-length limit and lacking enough
       information to uniquely identify the leaf slot-id on its own (for exam‐
       ple, missing the 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

       In  this	 example,  there  is  only one hotpluggable slot, pcie4 in the
       host. Connected under pcie4 is a	 third-party  expansion	 chassis  with
       hexadecimal  serial-id 4567812345678. Nested under the PCI Express slot
       pcie3 of that expansion	chassis	 (ApId	pcie4:iob4567812345678.pcie3),
       lies  another  third-party  expansion  chassis without a serial- id and
       with two hotpluggable PCI Express slots.

       Because the length of the absolute-slot-path form of:

	 pcie4/iob4567812345678.pcie3/iob.pcie1...2

       exceeds the ApId field length limit, and the leaf  slot-path  component
       is not globally unique, ap_id form (3) is used. ap_id form (2) is where
       slot-id form (3) (the default form) of the leaf slot-path component  in
       the absolute-slot-path is used as the final ApId.

       The   default   form   or  slot-id  form	 (3)  of  the  leaf  component
       .../iob.pcie1 represents a PCI Express slot with device number 0, bound
       to driver instance 20 of px_pci. Likewise, the default form of the leaf
       component .../iob.pcie2 represents a PCI Express slot with device  num‐
       ber 0, bound to driver instance 21 of px_pci.

FILES
       /usr/lib/cfgadm/shp.so.1

	   Hardware-specific library for PCI Express and Standard PCI hotplug‐
	   ging.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Availability		     │system/library		   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Uncommitted		   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       cfgadm(1M), cfgadm_pci(1M), hotplugd(1M), config_admin(3CFGADM), libcf‐
       gadm(3LIB), attributes(5), smf(5)

NOTES
       The  cfgadm_shp	library	 is dependent on the hotplug service, which is
       managed by smf(5) under FMRI:

	 svc:/system/hotplug:default

       The service must be enabled for	the  cfgadm_shp	 library  to  function
       properly. See hotplugd(1M) for details.

SunOS 5.10			  25 Aug 2009			cfgadm_shp(1M)
[top]

List of man pages available for SunOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net