CFGADM_SBD(8) Maintenance Commands and Procedures CFGADM_SBD(8)

NAME

cfgadm_sbd - cfgadm commands for system board administration

SYNOPSIS

cfgadm -l [-a] [-o parsable] ap_id...


cfgadm -c function [-f] [-y | -n]
[-o nopoweroff] [-v] ap_id...


cfgadm -t [-v] ap_id...


cfgadm -x [-f] [-v] function ap_id...

DESCRIPTION

The cfgadm_sbd plugin provides dynamic reconfiguration functionality
for connecting, configuring, unconfiguring, and disconnecting class
sbd system boards. It also enables you to connect or disconnect a
system board from a running system without having to reboot the
system.


The cfgadm command resides in /usr/sbin. See cfgadm(8). The
cfgadm_sbd plugin resides in /usr/platform/${arch}/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.

Component Conditions

The following are the names and descriptions of the component
conditions:

failed
The component failed testing.


ok
The component is operational.


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 operating
system.


unconfigured
The component is not available for use by the
operating system.

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 receptacle states
for boards:

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 disconnected state before you remove it from
the slot.


empty
A board is not present.


The occupant state of a disconnected board is always unconfigured.
The following table contains the names and descriptions of the
occupant states for boards:

configured
At least one component on the board is configured.


unconfigured
All of the components on the board are unconfigured.

State Change Functions

Functions that change the state of a board slot or a component on the
board can be issued concurrently against any attachment point. Only
one state changing operation is permitted 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

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.


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 process, 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. 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=ap_id:type:r_state:o_state:busy SB0 SB1

Ap_Id 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


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.

Ap_Id 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.

Ap_Id 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.

Ap_Id 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 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 sbd_options,platform=platform_options

OPTIONS

This man page does not include the -v, -a, -s, or -h options for the
cfgadm command. See cfgadm(8) for descriptions of those options. The
following options are supported by the cfgadm_sbd 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(8), psradm(8)
and psrinfo(8).

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) 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
monitor the progress of the operation
by issuing a status command against the
memory attachment point. You can also
interrupt the memory operation by
stopping the cfgadm command. 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 configured,
the disconnect function attempts to
unconfigure the occupant. It then
powers off the system board. At this
point, the board can be removed from
the slot.

If you specify -o nopoweroff, the
disconnect function leaves the board
powered on.


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 function, 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 function adds
the CPUs to the CPU list. For memory,
the configure 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(8)
and mount(8).


connect
Changes the receptacle state to
connected. This function applies only
to system board slots.

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.


-f
Overrides software state changing constraints.

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(8). The cfgadm_sbd
plugin provides specific information in the info field
as described below. The format of this information
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 one # is
present, this CPU
has multiple 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 multiple
active virtual
processors, the
ecache could either
be shared among the
virtual processors,
or divided between
them.


memory
The memory type displays the following
information, as appropriate:

address=#
Where # is a
number,
representing the
base physical
address.


size=#
Where # is a
number,
representing the
size of the memory
in KBytes.


permanent=#
Where # is a
number,
representing the
size of permanent
memory in KBytes.


unconfigurable
An operating
system setting
that prevents the
memory from being
unconfigured.


inter-board-interleave
The board is
participating in
interleaving with
other boards.


source=ap_id
Represents the
source attachment
point.


target=ap_id
Represents the
target attachment
point.


deleted=#
Where # is a
number,
representing the
amount of memory
that has already
been deleted in
KBytes.


remaining=#
Where # is a
number,
representing the
amount of memory
to be deleted in
KBytes.


io
The io type displays the following
information:

device=path
Represents the physical path
to the I/O component.


referenced
The I/O component is
referenced.


board
The board type displays the following
boolean name. If it are not present, then
the opposite applies.

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 conjunction with
the -s option. See the cfgadm(8) 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:

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 ap_id
The exact format depends on the platform and
typically corresponds to the physical labelling
on the machine.


Component ap_id
The component attachment point ID takes the form
component_typeX, where component_type equals one
of the component types described in "Component
Types" and X equals the component number. The
component number is a board-relative unit number.

The above convention does not apply to memory
components. Any DR action on a memory attachment
point affects all of the memory on the system
board.

EXAMPLES

The following examples show sample user input and system output.
User input, specifically references to attachment points, and system
output will differ between systems.

Example 1: Listing All of the System Board

# cfgadm -a -s "select=class(sbd)"

Ap_Id 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 conditions:


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)"

Ap_Id Type Receptacle Occupant Condition
SB0::cpu0 cpu connected configured ok
SB0::cpu1 cpu connected configured ok
SB0::cpu2 cpu connected configured ok
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=ap_id: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

ATTRIBUTES

See attributes(7) for a description of the following attribute:


+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|Stability | See below. |
+---------------+-----------------+


The interface stability is evolving. The output stability is
unstable.

SEE ALSO

config_admin(3CFGADM), attributes(7), cfgadm(8), devfsadm(8),
ifconfig(8), mount(8), pbind(8), psradm(8), psrinfo(8)

NOTES

This section contains information on how to monitor the progress of a
memory delete operation.

Memory Delete Monitoring

The following shell script can be used to monitor the progress of a
memory delete operation.

# cfgadm -c unconfigure -y SB0::memory &
# watch_memdel SB0

#!/bin/sh
# This is the watch_memdel script.

if [ -z "$1" ]; then
printf "usage: %s board_id\n" `basename $0`
exit 1
fi

board_id=$1

cfgadm_info='cfgadm -s noheadings,cols=info -o parsable'

eval `$cfgadm_info $board_id::memory`

if [ -z "$remaining" ]; then
echo no memory delete in progress involving $board_id
exit 0
fi

echo deleting target $target

while true
do
eval `$cfgadm_info $board_id::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


August 2, 2023 CFGADM_SBD(8)