System Administration Commands cfgadmsbd(1M)
NAME
cfgadmsbd - cfgadm commands for system board administration
SYNOPSIS
cfgadm -l [-a] [-o parsable] apid...
cfgadm -c function [-f] [-y -n]
[-o unassign nopoweroff] [-v] apid...
cfgadm -t [-v] apid...
cfgadm -x [-f] [-v] function apid...
DESCRIPTION
The cfgadmsbd plugin provides dynamic reconfiguration func-
tionality for connecting, configuring, unconfiguring, and
disconnecting class sbd system boards. It also enables you
to connect or disconnect a system board from a running sys-
tem without having to reboot the system.
The cfgadm command resides in /usr/sbin. See cfgadm(1M). The
cfgadmsbd plugin resides /usr/platform/sun4u/lib/cfgadm.
Each board slot appears as a single attachment point in the
device tree. Each component appears as a dynamic attachment
point. You can view the type, state, and condition of each
component, and the states and condition of each board slot
by using the -a option.
The cfgadm options perform differently depending on the
platform. Additionally, the form of the attachment points is
different depending on the platform. See the Platform Notes
section for more information.
Component Conditions
The following are the names and descriptions of the com-
ponent conditions:
failed The component failed testing.
ok The component is operational.
SunOS 5.11 Last change: 13 Oct 2003 1
System Administration Commands cfgadmsbd(1M)
unknown The component has not been tested.
Component States
The following is the name and description of the receptacle
state for components:
connected The component is connected to the board slot.
The following are the names and descriptions of the occupant
states for components:
configured The component is available for use by the
Solaris operating environment.
unconfigured The component is not available for use by
the Solaris operating environment.
Board Conditions
The following are the names and descriptions of the board
conditions.
failed The board failed testing.
ok The board is operational.
unknown The board has not been tested.
unusable The board slot is unusable.
Board States
Inserting a board changes the receptacle state from empty to
disconnected. Removing a board changes the receptacle state
from disconnected to empty.
Caution: Removing a board that is in the connected state or
that is powered on and in the disconnected state crashes the
operating system and can result in permanent damage to the
system.
The following are the names and descriptions of the recepta-
cle states for boards:
SunOS 5.11 Last change: 13 Oct 2003 2
System Administration Commands cfgadmsbd(1M)
connected The board is powered on and connected to the
system bus. You can view the components on a
board only after it is in the connected
state.
disconnected The board is disconnected from the system
bus. A board can be in the disconnected
state without being powered off. However, a
board must be powered off and in the discon-
nected state before you remove it from the
slot.
empty A board is not present.
The occupant state of a disconnected board is always uncon-
figured. The following table contains the names and descrip-
tions of the occupant states for boards:
configured At least one component on the board is con-
figured.
unconfigured All of the components on the board are
unconfigured.
Dynamic System Domains
Platforms based on dynamic system domains (DSDs, referred to
as domains in this document) divide the slots in the chassis
into electrically isolated hardware partitions (that is,
DSDs). Platforms that are not based on DSDs assign all slots
to the system permanently.
A slot can be empty or populated, and it can be assigned or
available to any number of domains. The number of slots
available to a given domain is controlled by an available
component list (ACL) that is maintained on the system con-
troller. The ACL is not the access control list provided by
the Solaris operating environment.
A slot is visible to a domain only if the slot is in the
domain's ACL and if it is not assigned to another domain. An
unassigned slot is visible to all domains that have the slot
in their ACL. After a slot has been assigned to a domain,
the slot is no longer visible to any other domain.
SunOS 5.11 Last change: 13 Oct 2003 3
System Administration Commands cfgadmsbd(1M)
A slot that is visible to a domain, but not assigned, must
first be assigned to the domain before any other state
changing commands are applied. The assign can be done expli-
citly using -x assign or implicitly as part of a connect. A
slot must be unassigned from a domain before it can be used
by another domain. The unassign is always explicit, either
directly using -x unassign or as an option to disconnect
using -o unassign.
State Change Functions
Functions that change the state of a board slot or a com-
ponent on the board can be issued concurrently against any
attachment point. Only one state changing operation is per-
mitted at a given time. A Y in the Busy field in the state
changing information indicates an operation is in progress.
The following list contains the functions that change the
state:
o configure
o unconfigure
o connect
o disconnect
Availability Change Functions
Commands that change the availability of a board can be
issued concurrently against any attachment point. Only one
availability change operation is permitted at a given time.
These functions also change the information string in the
cfgadm -l output. A Y in the Busy field indicates that an
operation is in progress.
The following list contains the functions that change the
availability:
o assign
o unassign
Condition Change Functions
Functions that change the condition of a board slot or a
component on the board can be issued concurrently against
any attachment point. Only one condition change operation is
permitted at a given time. These functions also change the
information string in the cfgadm -l output. A Y in the Busy
field indicates an operation is in progress.
SunOS 5.11 Last change: 13 Oct 2003 4
System Administration Commands cfgadmsbd(1M)
The following list contains the functions that change the
condition:
o poweron
o poweroff
o test
Unconfigure Process
This section contains a description of the unconfigure pro-
cess, and illustrates the states of source and target boards
at different stages during the process of moving permanent
memory.
In the following code examples, the permanent memory on
board 0 must be moved to another board in the domain. Thus,
board 0 is the source, and board 1 is the target.
A status change operation cannot be initiated on a board
while it is marked as busy. For brevity, the CPU information
has been removed from the code examples.
The process is started with the following command:
# cfgadm -c unconfigure -y SB0::memory &
First, the memory on board 1 in the same address range as
the permanent memory on board 0 must be deleted. During this
phase, the source board, the target board, and the memory
attachment points are marked as busy. You can display the
status with the following command:
# cfgadm -a -s cols=apid:type:rstate:ostate:busy SB0 SB1
ApId Type Receptacle Occupant Busy
SB0 CPU connected configured y
SB0::memory memory connected configured y
SB1 CPU connected configured y
SB1::memory memory connected configured y
SunOS 5.11 Last change: 13 Oct 2003 5
System Administration Commands cfgadmsbd(1M)
After the memory has been deleted on board 1, it is marked
as unconfigured. The memory on board 0 remains configured,
but it is still marked as busy, as in the following example.
ApId Type Receptacle Occupant Busy
SB0 CPU connected configured y
SB0::memory memory connected configured y
SB1 CPU connected configured y
SB1::memory memory connected unconfigured n
The memory from board 0 is then copied to board 1. After it
has been copied, the occupant state for the memory is
switched. The memory on board 0 becomes unconfigured, and
the memory on board 1 becomes configured. At this point in
the process, only board 0 remains busy, as in the following
example.
ApId Type Receptacle Occupant Busy
SB0 CPU connected configured y
SB0::memory memory connected unconfigured n
SB1 CPU connected configured n
SB1::memory memory connected configured n
After the entire process has been completed, the memory on
board 0 remains unconfigured, and the attachment points are
not busy, as in the following example.
ApId Type Receptacle Occupant Busy
SB0 CPU connected configured n
SB0::memory memory connected unconfigured n
SB1 CPU connected configured n
SB1::memory memory connected configured n
The permanent memory has been moved, and the memory on board
0 has been unconfigured. At this point, you can initiate a
new state changing operation on either board.
Platform-Specific Options
You can specify platform-specific options that follow the
options interpreted by the system board plugin. All
SunOS 5.11 Last change: 13 Oct 2003 6
System Administration Commands cfgadmsbd(1M)
platform-specific options must be preceded by the platform
keyword. The following example contains the general format
of a command with platform-specific options:
command -o sbdoptions,platform=platformoptions
OPTIONS
This man page does not include the -v, -a, -s, or -h options
for the cfgadm command. See cfgadm(1M) for descriptions of
those options. The following options are supported by the
cfgadmsbd plugin:
-c function Performs a state change function. You can use
the following functions:
unconfigure Changes the occupant state to
unconfigured. This function
applies to system board slots
and to all of the components
on the system board.
The unconfigure function
removes the CPUs from the CPU
list and deletes the physical
memory from the system memory
pool. If any device is still
in use, the cfgadm command
fails and reports the failure
to the user. You can retry the
command as soon as the device
is no longer busy. If a CPU is
in use, you must ensure that
it is off line before you
proceed. See pbind(1M),
psradm(1M) and psrinfo(1M).
The unconfigure function moves
the physical memory to another
system board before it deletes
the memory from the board you
want to unconfigure. Depending
of the type of memory being
moved, the command fails if it
cannot find enough memory on
another board or if it cannot
find an appropriate physical
memory range.
For permanent memory, the
operating system must be
suspended (that is, quiesced)
SunOS 5.11 Last change: 13 Oct 2003 7
System Administration Commands cfgadmsbd(1M)
while the memory is moved and
the memory controllers are
reprogrammed. If the operating
system must be suspended, you
will be prompted to proceed
with the operation. You can
use the -y or -n options to
always answer yes or no
respectively.
Moving memory can take several
minutes to complete, depending
on the amount of memory and
the system load. You can moni-
tor the progress of the opera-
tion by issuing a status com-
mand against the memory
attachment point. You can also
interrupt the memory operation
by stopping the cfgadm com-
mand. The deleted memory is
returned to the system memory
pool.
disconnect Changes the receptacle state
to disconnected. This function
applies only to system board
slots.
If the occupant state is con-
figured, the disconnect func-
tion attempts to unconfigure
the occupant. It then powers
off the system board. At this
point, the board can be
removed from the slot.
This function leaves the board
in the assigned state on plat-
forms that support dynamic
system domains.
If you specify -o nopoweroff,
the disconnect function leaves
the board powered on. If you
specify -o unassign, the
disconnect function unassigns
the board from the domain.
If you unassign a board from a
domain, you can assign it to
SunOS 5.11 Last change: 13 Oct 2003 8
System Administration Commands cfgadmsbd(1M)
another domain. However, if it
is assigned to another domain,
it is not available to the
domain from which is was unas-
signed.
configure Changes the occupant state to
configured. This function
applies to system board slots
and to any components on the
system board.
If the receptacle state is
disconnected, the configure
function attempts to connect
the receptacle. It then walks
the tree of devices that is
created by the connect func-
tion, and attaches the devices
if necessary. Running this
function configures all of the
components on the board,
except those that have already
been configured.
For CPUs, the configure func-
tion adds the CPUs to the CPU
list. For memory, the config-
ure function ensures that the
memory is initialized then
adds the memory to the system
memory pool. The CPUs and the
memory are ready for use after
the configure function has
been completed successfully.
For I/O devices, you must use
the mount and the ifconfig
commands before the devices
can be used. See ifconfig(1M)
and mount(1M).
connect Changes the receptacle state
to connected. This function
applies only to system board
slots.
If the board slot is not
assigned to the domain, the
connect function attempts to
SunOS 5.11 Last change: 13 Oct 2003 9
System Administration Commands cfgadmsbd(1M)
assign the slot to the domain.
Next, it powers on and tests
the board, then it connects
the board electronically to
the system bus and probes the
components.
After the connect function is
completed successfully, you
can use the -a option to view
the status of the components
on the board. The connect
function leaves all of the
components in the unconfigured
state.
The assignment step applies
only to platforms that support
dynamic system domains.
-f Overrides software state changing con-
straints.
The -f option never overrides fundamental
safety and availability constraints of the
hardware and operating system.
-l Lists the state and condition of attachment
points specified in the format controlled by
the -s, -v, and -a options as specified in
cfgadm(1M). The cfgadmsbd plugin provides
specific information in the info field as
described below. The format of this informa-
tion might be altered by the -o parsable
option.
The parsable info field is composed of the
following:
cpu The cpu type displays the following
information:
cpuid=#[,#...] Where # is
a number,
and
represents
the ID of
the CPU. If
more than
SunOS 5.11 Last change: 13 Oct 2003 10
System Administration Commands cfgadmsbd(1M)
one # is
present,
this CPU
has multi-
ple active
virtual
processors.
speed=# Where # is
a number
and
represents
the speed
of the CPU
in MHz.
ecache=# Where # is
a number
and
represents
the size of
the ecache
in MBytes.
If the CPU
has multi-
ple active
virtual
processors,
the ecache
could
either be
shared
among the
virtual
processors,
or divided
between
them.
memory The memory type displays the fol-
lowing information, as appropriate:
address=# Where #
is a
number,
represent-
ing the
base
SunOS 5.11 Last change: 13 Oct 2003 11
System Administration Commands cfgadmsbd(1M)
physical
address.
size=# Where #
is a
number,
represent-
ing the
size of
the
memory in
KBytes.
permanent=# Where #
is a
number,
represent-
ing the
size of
permanent
memory in
KBytes.
unconfigurable An
operating
system
setting
that
prevents
the
memory
from
being
unconfig-
ured.
inter-board-interleave The board
is parti-
cipating
in inter-
leaving
with
other
boards.
source=apid Represents
the
SunOS 5.11 Last change: 13 Oct 2003 12
System Administration Commands cfgadmsbd(1M)
source
attach-
ment
point.
target=apid Represents
the tar-
get
attach-
ment
point.
deleted=# Where #
is a
number,
represent-
ing the
amount of
memory
that has
already
been
deleted
in
KBytes.
remaining=# Where #
is a
number,
represent-
ing the
amount of
memory to
be
deleted
in
KBytes.
io The io type displays the following
information:
device=path Represents the phy-
sical path to the
I/O component.
SunOS 5.11 Last change: 13 Oct 2003 13
System Administration Commands cfgadmsbd(1M)
referenced The I/O component is
referenced.
board The board type displays the follow-
ing boolean names. If they are not
present, then the opposite applies.
assigned The board is assigned
to the domain.
powered-on The board is powered
on.
The same items appear in the info
field in a more readable format if
the -o parsable option is not
specified.
-o parsable Returns the information in the info field as
a boolean name or a set of name=value pairs,
separated by a space character.
The -o parsable option can be used in con-
junction with the -s option. See the
cfgadm(1M) man page for more information
about the -s option.
-t Tests the board.
Before a board can be connected, it must pass
the appropriate level of testing.
Use of this option always attempts to test
the board, even if it has already passed the
appropriate level of testing. Testing is also
performed when a -c connect state change
function is issued, in which case the test
step can be skipped if the board already
shows an appropriate level of testing. Thus
the -t option can be used to explicitly
request that the board be tested.
-x function Performs an sbd-class function. You can use
the following functions:
SunOS 5.11 Last change: 13 Oct 2003 14
System Administration Commands cfgadmsbd(1M)
assign Assigns a board to a domain.
The receptacle state must be
disconnected or empty. The board
must also be listed in the domain
available component list. See
Dynamic System Domains.
unassign Unassigns a board from a domain.
The receptacle state must be
disconnected or empty. The board
must also be listed in the domain
available component list. See
Dynamic System Domains.
poweron Powers the system board on.
The receptacle state must be
disconnected.
poweroff Powers the system board off.
The receptacle state must be
disconnected.
OPERANDS
The following operands are supported:
Receptacle apid For the Sun Fire high-end systems such
as the Sun Fire 15K , the receptacle
attachment point ID takes the form SBX
or IOX, where X equals the slot number.
The exact format depends on the platform
and typically corresponds to the physi-
cal labelling on the machine. See the
platform specific information in the
NOTES section.
Component apid The component attachment point ID takes
the form componenttypeX, where
componenttype equals one of the com-
ponent types described in "Component
Types" and X equals the component
number. The component number is a
SunOS 5.11 Last change: 13 Oct 2003 15
System Administration Commands cfgadmsbd(1M)
board-relative unit number.
The above convention does not apply to
memory compontents. Any DR action on a
memory attachment point affects all of
the memory on the system board.
EXAMPLES
The following examples show user input and system output on
a Sun Fire 15K system. User input, specifically references
to attachment points and system output might differ on other
Sun Fire systems, such as the Sun Fire midrange systems such
as the 6800. Refer to the Platform Notes for specific infor-
mation about using the cfgadmsbd plugin on non-Sun Fire
high-end models.
Example 1 Listing All of the System Board
# cfgadm -a -s "select=class(sbd)"
ApId Type Receptacle Occupant Condition
SB0 CPU connected configured ok
SB0::cpu0 cpu connected configured ok
SB0::memory memory connected configured ok
IO1 HPCI connected configured ok
IO1::pci0 io connected configured ok
IO1::pci1 io connected configured ok
SB2 CPU disconnected unconfigured failed
SB3 CPU disconnected unconfigured unusable
SB4 unknown empty unconfigured unknown
This example demonstrates the mapping of the following con-
ditions:
o The board in Slot 2 failed testing.
o Slot 3 is unusable; thus, you cannot hot plug a
board into that slot.
Example 2 Listing All of the CPUs on the System Board
# cfgadm -a -s "select=class(sbd):type(cpu)"
ApId Type Receptacle Occupant Condition
SB0::cpu0 cpu connected configured ok
SB0::cpu1 cpu connected configured ok
SB0::cpu2 cpu connected configured ok
SunOS 5.11 Last change: 13 Oct 2003 16
System Administration Commands cfgadmsbd(1M)
SB0::cpu3 cpu connected configured ok
Example 3 Displaying the CPU Information Field
# cfgadm -l -s noheadings,cols=info SB0::cpu0
cpuid 16, speed 400 MHz, ecache 8 Mbytes
Example 4 Displaying the CPU Information Field in Parsable
Format
# cfgadm -l -s noheadings,cols=info -o parsable SB0::cpu0
cpuid=16 speed=400 ecache=8
Example 5 Displaying the Devices on an I/O Board
# cfgadm -a -s noheadings,cols=apid:info -o parsable IO1
IO1 powered-on assigned
IO1::pci0 device=/devices/saf@0/pci@0,2000 referenced
IO1::pci1 device=/devices/saf@0/pci@1,2000 referenced
Example 6 Monitoring an Unconfigure Operation
In the following example, the memory sizes are displayed in
Kbytes.
# cfgadm -c unconfigure -y SB0::memory &
# cfgadm -l -s noheadings,cols=info -o parsable SB0::memory SB1::memory
address=0x0 size=2097152 permanent=752592 target=SB1::memory
deleted=1273680 remaining=823472
address=0x1000000 size=2097152 source=SB0::memory
Example 7 Assigning a Slot to a Domain
# cfgadm -x assign SB2
SunOS 5.11 Last change: 13 Oct 2003 17
System Administration Commands cfgadmsbd(1M)
Example 8 Unassigning a Slot from a Domain
# cfgadm -x unassign SB3
ATRIBUTES
See attributes(5) for a description of the following attri-
bute:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWkvm.u
Stability See below.
The interface stability is evolving. The output stability is
unstable.
SEE ALSO
cfgadm(1M), devfsadm(1M), ifconfig(1M), mount(1M),
pbind(1M), psradm(1M), psrinfo(1M), configadmin(3CFGADM),
attributes(5)
NOTES
This section contains information on how to monitor the pro-
gress of a memory delete operation. It also contains plat-
form specific information.
Memory Delete Monitoring
The following shell script can be used to monitor the pro-
gress of a memory delete operation.
# cfgadm -c unconfigure -y SB0::memory &
# watchmemdel SB0
#!/bin/sh
# This is the watchmemdel script.
if [ -z "$1" ]; then
printf "usage: %s boardid\n" `basename $0`
exit 1
fi
boardid=$1
SunOS 5.11 Last change: 13 Oct 2003 18
System Administration Commands cfgadmsbd(1M)
cfgadminfo='cfgadm -s noheadings,cols=info -o parsable'
eval `$cfgadminfo $boardid::memory`
if [ -z "$remaining" ]; then
echo no memory delete in progress involving $boardid
exit 0
fi
echo deleting target $target
while true
do
eval `$cfgadminfo $boardid::memory`
if [ -n "$remaining" -a "$remaining" -ne 0 ]
then
echo $deleted KBytes deleted, $remaining KBytes remaining
remaining=
else
echo memory delete is done
exit 0
fi
sleep 1
done
exit 0
Sun Enterprise 10000 Platform Notes
The following syntax is used to refer to Platform Notes
attachment points on the Sun Enterprise 10000 system:
board::component
where board refers to the system board; and component
refers to the individual component. System boards can range
from SB0 (zero) to SB15. A maximum of sixteen system boards
are available.
The DR 3.0 model running on a Sun Enterprise 10000 domain
supports a limited subset of the functionality provided by
the cfgadmsbd plugin. The only supported operation is to
view the status of attachment points in the domain. This
corresponds to the -l option and all of its associated
options.
SunOS 5.11 Last change: 13 Oct 2003 19
System Administration Commands cfgadmsbd(1M)
Attempting to perform any other operation from the domain
will result in an error that states that the operation is
not supported. All operations to add or remove a system
board must be initiated from the System Service Processor.
Sun Fire High-End System Platform Notes
The following syntax is used to refer to attachment points
on the Sun Fire high-end systems:
board::component
where board refers to the system board or I/O board; and
component refers to the individual component.
Depending on the system's configuration, system boards can
range from SB0 (zero) through SB17, and I/O boards can range
from IO0 (IO zero) through IO17. (A maximum of eighteen sys-
tem and I/O boards are available).
The -t and -x options behave differently on the Sun Fire
high-end system platforms. The following list describes
their behavior:
-t The system controller uses a CPU to
test system boards by running LPOST,
sequenced by the hpost command. To
test I/O boards, the driver starts
the testing in response to the -t
option, and the test runs automati-
cally without user intervention. The
driver unconfigures a CPU and a
stretch of contiguous physical
memory. Then, it sends a command to
the system controller to test the
board. The system controller uses
the CPU and memory to test the I/O
board from inside of a
transaction/error cage. You can only
use CPUs from system boards (not
MCPU boards) to test I/O boards.
-x assign unassign In the Sun Fire high-end system
administration model, the platform
administrator controls the platform
hardware through the use of an
available component list for each
SunOS 5.11 Last change: 13 Oct 2003 20
System Administration Commands cfgadmsbd(1M)
domain. This information is main-
tained on the system controller.
Only the platform administrator can
modify the available component list
for a domain.
The domain administrator is only
allowed to assign or unassign a
board if it is in the available com-
ponent list for that domain. The
platform administrator does not have
this restriction, and can assign or
unassign a board even if it is not
in the available component list for
a domain.
Sun Fire 15K Component Types
The following are the names and descriptions of the com-
ponent types:
cpu CPU
io I/O device
memory Memory
Note: An operation on a memory component affects all of the
memory components on the board.
Sun Fire Midrange Systems Platform Notes
References to attachment points are slightly different on
Sun Fire midrange servers such as the 6800, 4810, 4800, and
3800 systems than on the Sun Fire high-end systems. The fol-
lowing syntax is used to refer to attachment points on Sun
Fire systems other than the Sun Fire 15K:
N#.board::component
where N# refers to the node; board refers to the system
board or I/O board; and component refers to the individual
component.
SunOS 5.11 Last change: 13 Oct 2003 21
System Administration Commands cfgadmsbd(1M)
Depending on the system's configuration, system boards can
range from SB0 through SB5, and I/O boards can range from
IB6 through IB9. (A maximum of six system and four I/O
boards are available).
Sun Fire Midrange System Component Types
The following are the names and descriptions of the com-
ponent types:
cpu CPU
pci I/O device
memory Memory
Note: An operation on a memory component affects all of the
memory components on the board.
SunOS 5.11 Last change: 13 Oct 2003 22
|
