'\" te
.\" Copyright 2023 Peter Tribble
.\" Copyright 2003 (c), Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH CFGADM_SBD 8 "August 2, 2023"
.SH NAME
cfgadm_sbd \- \fBcfgadm\fR commands for system board administration
.SH SYNOPSIS
.nf
\fBcfgadm \fR \fB-l\fR [\fB-a\fR] [\fB-o\fR parsable] \fI ap_id\fR...
.fi

.LP
.nf
\fBcfgadm \fR \fB-c \fR \fIfunction\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR]
     [\fB-o\fR nopoweroff] [\fB-v\fR] \fI ap_id\fR...
.fi

.LP
.nf
\fBcfgadm \fR \fB-t\fR [\fB-v\fR] \fI ap_id\fR...
.fi

.LP
.nf
\fBcfgadm \fR \fB-x \fR [\fB-f\fR] [\fB-v\fR] \fIfunction\fR \fI ap_id\fR...
.fi

.SH DESCRIPTION
The \fBcfgadm_sbd\fR plugin provides dynamic reconfiguration functionality for
connecting, configuring, unconfiguring, and disconnecting class \fBsbd\fR
system boards. It also enables you to connect or disconnect a system board from
a running system without having to reboot the system.
.sp
.LP
The \fBcfgadm\fR command resides in \fB/usr/sbin\fR. See \fBcfgadm\fR(8). The
\fBcfgadm_sbd\fR plugin resides in \fB/usr/platform/${arch}/lib/cfgadm\fR.
.sp
.LP
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 \fB-a\fR option.
.sp
.LP
The \fBcfgadm\fR options perform differently depending on the platform.
Additionally, the form of the attachment points is different depending on the
platform.
.SS "Component Conditions"
The following are the names and descriptions of the component conditions:
.sp
.ne 2
.na
\fBfailed\fR
.ad
.RS 11n
The component failed testing.
.RE

.sp
.ne 2
.na
\fBok\fR
.ad
.RS 11n
The component is operational.
.RE

.sp
.ne 2
.na
\fBunknown\fR
.ad
.RS 11n
The component has not been tested.
.RE

.SS "Component States"
The following is the name and description of the receptacle state for
components:
.sp
.ne 2
.na
\fBconnected\fR
.ad
.RS 13n
The component is connected to the board slot.
.RE

.sp
.LP
The following are the names and descriptions of the occupant states for
components:
.sp
.ne 2
.na
\fBconfigured\fR
.ad
.RS 16n
The component is available for use by the operating system.
.RE

.sp
.ne 2
.na
\fBunconfigured\fR
.ad
.RS 16n
The component is not available for use by the operating system.
.RE

.SS "Board Conditions"
The following are the names and descriptions of the board conditions.
.sp
.ne 2
.na
\fBfailed\fR
.ad
.RS 12n
The board failed testing.
.RE

.sp
.ne 2
.na
\fBok\fR
.ad
.RS 12n
The board is operational.
.RE

.sp
.ne 2
.na
\fBunknown\fR
.ad
.RS 12n
The board has not been tested.
.RE

.sp
.ne 2
.na
\fBunusable\fR
.ad
.RS 12n
The board slot is unusable.
.RE

.SS "Board States"
Inserting a board changes the receptacle state from empty to disconnected.
Removing a board changes the receptacle state from disconnected to empty.
.sp
.LP
\fBCaution:\fR 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.
.sp
.LP
The following are the names and descriptions of the receptacle states for
boards:
.sp
.ne 2
.na
\fBconnected\fR
.ad
.RS 16n
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.
.RE

.sp
.ne 2
.na
\fBdisconnected\fR
.ad
.RS 16n
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.
.RE

.sp
.ne 2
.na
\fBempty\fR
.ad
.RS 16n
A board is not present.
.RE

.sp
.LP
The occupant state of a disconnected board is always unconfigured. The
following table contains the names and descriptions of the occupant states for
boards:
.sp
.ne 2
.na
\fBconfigured\fR
.ad
.RS 16n
At least one component on the board is configured.
.RE

.sp
.ne 2
.na
\fBunconfigured\fR
.ad
.RS 16n
All of the components on the board are unconfigured.
.RE

.SS "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 \fBY\fR in the Busy field in the
state changing information indicates an operation is in progress.
.sp
.LP
The following list contains the functions that change the state:
.RS +4
.TP
.ie t \(bu
.el o
configure
.RE
.RS +4
.TP
.ie t \(bu
.el o
unconfigure
.RE
.RS +4
.TP
.ie t \(bu
.el o
connect
.RE
.RS +4
.TP
.ie t \(bu
.el o
disconnect
.RE
.SS "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 \fBcfgadm\fR \fB-l\fR output. A \fBY\fR in the Busy
field indicates an operation is in progress.
.sp
.LP
The following list contains the functions that change the condition:
.RS +4
.TP
.ie t \(bu
.el o
\fBpoweron\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBpoweroff\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBtest\fR
.RE
.SS "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.
.sp
.LP
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.
.sp
.LP
A status change operation cannot be initiated on a board while it is marked as
busy. For brevity, the \fBCPU\fR information has been removed from the code
examples.
.sp
.LP
The process is started with the following command:
.sp
.in +2
.nf
# \fBcfgadm -c unconfigure -y SB0::memory &\fR
.fi
.in -2
.sp

.sp
.LP
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:
.sp
.in +2
.nf
# \fBcfgadm -a -s cols=ap_id:type:r_state:o_state:busy SB0 SB1\fR

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

.fi
.in -2
.sp

.sp
.LP
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.
.sp
.in +2
.nf
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

.fi
.in -2
.sp

.sp
.LP
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.
.sp
.in +2
.nf
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

.fi
.in -2
.sp

.sp
.LP
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.
.sp
.in +2
.nf
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

.fi
.in -2
.sp

.sp
.LP
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.
.SS "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 \fBplatform\fR keyword. The following example contains the general format
of a command with platform-specific options:
.sp
.LP
\fB\fIcommand\fR -o \fIsbd_options\fR,platform=\fIplatform_options\fR\fR
.SH OPTIONS
This man page does not include the \fB-v\fR, \fB-a\fR, \fB-s\fR, or \fB-h\fR
options for the \fBcfgadm\fR command. See \fBcfgadm\fR(8) for descriptions of
those options. The following options are supported by the \fBcfgadm_sbd\fR
plugin:
.sp
.ne 2
.na
\fB\fB-c \fR\fIfunction\fR\fR
.ad
.RS 15n
Performs a state change function. You can use the following functions:
.sp
.ne 2
.na
\fBunconfigure\fR
.ad
.RS 15n
Changes the occupant state to unconfigured. This function applies to system
board slots and to all of the components on the system board.
.sp
The \fBunconfigure\fR function removes the \fBCPU\fRs from the \fBCPU\fR list
and deletes the physical memory from the system memory pool. If any device is
still in use, the \fBcfgadm\fR 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
\fBCPU\fR is in use, you must ensure that it is off line before you proceed.
See \fBpbind\fR(8), \fBpsradm\fR(8) and \fBpsrinfo\fR(8).
.sp
The \fBunconfigure\fR 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.
.sp
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 \fB-y\fR or \fB-n\fR options to
always answer yes or no respectively.
.sp
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 \fBcfgadm\fR command. The
deleted memory is returned to the system memory pool.
.RE

.sp
.ne 2
.na
\fBdisconnect\fR
.ad
.RS 15n
Changes the receptacle state to disconnected. This function applies only to
system board slots.
.sp
If the occupant state is configured, the \fBdisconnect\fR function attempts to
unconfigure the occupant. It then powers off the system board. At this point,
the board can be removed from the slot.
.sp
If you specify \fB-o nopoweroff\fR, the \fBdisconnect\fR function leaves the
board powered on.
.RE

.sp
.ne 2
.na
\fBconfigure\fR
.ad
.RS 15n
Changes the occupant state to configured. This function applies to system board
slots and to any components on the system board.
.sp
If the receptacle state is disconnected, the \fBconfigure\fR function attempts
to connect the receptacle. It then walks the tree of devices that is created by
the \fBconnect\fR 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.
.sp
For \fBCPU\fRs, the \fBconfigure\fR function adds the \fBCPU\fRs to the
\fBCPU\fR list. For memory, the \fBconfigure\fR function ensures that the
memory is initialized then adds the memory to the system memory pool. The
\fBCPU\fRs and the memory are ready for use after the \fBconfigure\fR function
has been completed successfully.
.sp
For I/O devices, you must use the \fBmount\fR and the \fBifconfig\fR commands
before the devices can be used. See \fBifconfig\fR(8) and \fBmount\fR(8).
.RE

.sp
.ne 2
.na
\fBconnect\fR
.ad
.RS 15n
Changes the receptacle state to connected. This function applies only to system
board slots.
.sp
After the \fBconnect\fR function is completed successfully, you can use the
\fB-a\fR option to view the status of the components on the board. The
\fBconnect\fR function leaves all of the components in the unconfigured state.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 15n
Overrides software state changing constraints.
.sp
The \fB-f\fR option never overrides fundamental safety and availability
constraints of the hardware and operating system.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 15n
Lists the state and condition of attachment points specified in the format
controlled by the \fB-s\fR, \fB-v\fR, and \fB-a\fR options as specified in
\fBcfgadm\fR(8). The \fBcfgadm_sbd\fR plugin provides specific information in
the info field as described below. The format of this information might be
altered by the \fB\fR\fB-o\fR\fB parsable\fR option.
.sp
The parsable \fBinfo\fR field is composed of the following:
.sp
.ne 2
.na
\fBcpu\fR
.ad
.RS 10n
The \fBcpu\fR type displays the following information:
.sp
.ne 2
.na
\fB\fBcpuid=\fR\fI#\fR\fB[,\fR\fI#\fR\fB\&.\|.\|.]\fR\fR
.ad
.RS 24n
Where \fI#\fR is a number, and represents the \fBID\fR of the \fBCPU\fR. If
more than one \fI#\fR is present, this \fBCPU\fR has multiple active virtual
processors.
.RE

.sp
.ne 2
.na
\fB\fBspeed=\fR\fI#\fR\fR
.ad
.RS 24n
Where \fI#\fR is a number and represents the speed of the \fBCPU\fR in
\fBMHz\fR.
.RE

.sp
.ne 2
.na
\fB\fBecache=\fR\fI#\fR\fR
.ad
.RS 24n
Where \fI#\fR is a number and represents the size of the ecache in MBytes. If
the \fBCPU\fR has multiple active virtual processors, the ecache could either
be shared among the virtual processors, or divided between them.
.RE

.RE

.sp
.ne 2
.na
\fBmemory\fR
.ad
.RS 10n
The \fBmemory\fR type displays the following information, as appropriate:
.sp
.ne 2
.na
\fBaddress=\fI#\fR\fR
.ad
.RS 26n
Where \fI#\fR is a number, representing the base physical address.
.RE

.sp
.ne 2
.na
\fBsize=\fI#\fR\fR
.ad
.RS 26n
Where \fI#\fR is a number, representing the size of the memory in \fBKBytes\fR.
.RE

.sp
.ne 2
.na
\fBpermanent=\fI#\fR\fR
.ad
.RS 26n
Where \fI#\fR is a number, representing the size of permanent memory in
\fBKBytes\fR.
.RE

.sp
.ne 2
.na
\fBunconfigurable\fR
.ad
.RS 26n
An operating system setting that prevents the memory from being unconfigured.
.RE

.sp
.ne 2
.na
\fBinter-board-interleave\fR
.ad
.RS 26n
The board is participating in interleaving with other boards.
.RE

.sp
.ne 2
.na
\fBsource=\fIap_id\fR\fR
.ad
.RS 26n
Represents the source attachment point.
.RE

.sp
.ne 2
.na
\fBtarget=\fIap_id\fR\fR
.ad
.RS 26n
Represents the target attachment point.
.RE

.sp
.ne 2
.na
\fBdeleted=\fI#\fR\fR
.ad
.RS 26n
Where \fI#\fR is a number, representing the amount of memory that has already
been deleted in \fBKBytes\fR.
.RE

.sp
.ne 2
.na
\fBremaining=\fI#\fR\fR
.ad
.RS 26n
Where \fI#\fR is a number, representing the amount of memory to be deleted in
\fBKBytes\fR.
.RE

.RE

.sp
.ne 2
.na
\fBio\fR
.ad
.RS 10n
The \fBio\fR type displays the following information:
.sp
.ne 2
.na
\fBdevice=\fIpath\fR\fR
.ad
.RS 15n
Represents the physical path to the I/O component.
.RE

.sp
.ne 2
.na
\fBreferenced\fR
.ad
.RS 15n
The I/O component is referenced.
.RE

.RE

.sp
.ne 2
.na
\fBboard\fR
.ad
.RS 10n
The \fBboard\fR type displays the following boolean name. If it are not
present, then the opposite applies.
.sp
.ne 2
.na
\fBpowered-on\fR
.ad
.RS 14n
The board is powered on.
.RE

The same items appear in the \fBinfo\fR field in a more readable format if the
\fB-o\fR \fBparsable\fR option is not specified.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-o\fR parsable\fR
.ad
.RS 15n
Returns the information in the \fBinfo\fR field as a boolean \fIname\fR or a
set of \fBname=value\fR pairs, separated by a space character.
.sp
The \fB-o parsable\fR option can be used in conjunction with the \fB-s\fR
option. See the \fBcfgadm\fR(8) man page for more information about the
\fB-s\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 15n
Tests the board.
.sp
Before a board can be connected, it must pass the appropriate level of testing.
.sp
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
\fB\fR\fB-c\fR\fB connect\fR 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 \fB-t\fR option can be used to explicitly request that the
board be tested.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fI function\fR\fR
.ad
.RS 15n
Performs an sbd-class function. You can use the following functions:
.sp
.ne 2
.na
\fBpoweron\fR
.ad
.RS 12n
Powers the system board on.
.sp
The receptacle state must be disconnected.
.RE

.sp
.ne 2
.na
\fBpoweroff\fR
.ad
.RS 12n
Powers the system board off.
.sp
The receptacle state must be disconnected.
.RE

.RE

.SH OPERANDS
The following operands are supported:
.sp
.ne 2
.na
\fBReceptacle \fIap_id\fR\fR
.ad
.RS 20n
The exact format depends on the platform and typically corresponds to the
physical labelling on the machine.
.RE

.sp
.ne 2
.na
\fBComponent \fIap_id\fR\fR
.ad
.RS 20n
The component attachment point \fBID\fR takes the form \fIcomponent_typeX\fR,
where \fIcomponent_type\fR equals one of the component types described in
"Component Types" and \fIX\fR equals the component number. The component number
is a board-relative unit number.
.sp
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.
.RE

.SH 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.
.LP
\fBExample 1 \fRListing All of the System Board
.sp
.in +2
.nf
# \fBcfgadm -a -s "select=class(sbd)"\fR

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
.fi
.in -2
.sp

.sp
.LP
This example demonstrates the mapping of the following conditions:

.RS +4
.TP
.ie t \(bu
.el o
The board in Slot 2 failed testing.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Slot 3 is unusable; thus, you cannot hot plug a board into that slot.
.RE
.LP
\fBExample 2 \fRListing All of the \fBCPU\fRs on the System Board
.sp
.in +2
.nf
# \fBcfgadm -a -s "select=class(sbd):type(cpu)"\fR

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
.fi
.in -2
.sp

.LP
\fBExample 3 \fRDisplaying the \fBCPU\fR Information Field
.sp
.in +2
.nf
# \fBcfgadm -l -s noheadings,cols=info SB0::cpu0\fR

cpuid 16, speed 400 MHz, ecache 8 Mbytes
.fi
.in -2
.sp

.LP
\fBExample 4 \fRDisplaying the \fBCPU\fR Information Field in Parsable Format
.sp
.in +2
.nf
# \fBcfgadm -l -s noheadings,cols=info -o parsable SB0::cpu0\fR

cpuid=16 speed=400 ecache=8
.fi
.in -2
.sp

.LP
\fBExample 5 \fRDisplaying the Devices on an I/O Board
.sp
.in +2
.nf
# \fBcfgadm -a -s noheadings,cols=ap_id:info -o parsable IO1\fR

IO1       powered-on assigned
IO1::pci0 device=/devices/saf@0/pci@0,2000 referenced
IO1::pci1 device=/devices/saf@0/pci@1,2000 referenced
.fi
.in -2
.sp

.LP
\fBExample 6 \fRMonitoring an Unconfigure Operation
.sp
.LP
In the following example, the memory sizes are displayed in Kbytes.

.sp
.in +2
.nf
# \fBcfgadm -c unconfigure -y SB0::memory &\fR
# \fBcfgadm -l -s noheadings,cols=info -o parsable SB0::memory SB1::memory\fR

address=0x0 size=2097152 permanent=752592 target=SB1::memory
     deleted=1273680 remaining=823472
address=0x1000000 size=2097152 source=SB0::memory
.fi
.in -2
.sp

.SH ATTRIBUTES
See \fBattributes\fR(7) for a description of the following attribute:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Stability	See below.
.TE

.sp
.LP
The interface stability is evolving. The output stability is unstable.
.SH SEE ALSO
.BR config_admin (3CFGADM),
.BR attributes (7),
.BR cfgadm (8),
.BR devfsadm (8),
.BR ifconfig (8),
.BR mount (8),
.BR pbind (8),
.BR psradm (8),
.BR psrinfo (8)
.SH NOTES
This section contains information on how to monitor the progress of a memory
delete operation.
.SS "Memory Delete Monitoring"
The following shell script can be used to monitor the progress of a memory
delete operation.
.sp
.in +2
.nf
# \fBcfgadm -c unconfigure -y SB0::memory &\fR
# \fBwatch_memdel SB0\fR

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

if [ -z "$1" ]; then
        printf "usage:  %s board_id\en" `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
.fi
.in -2
.sp