'\" te
.\" Copyright (c) 1999 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_sysctrl 1M "10 Mar 1999" "SunOS 5.11" "System Administration Commands"
.SH NAME
cfgadm_sysctrl \- EXX00 system board administration
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/cfgadm\fR \fB-c\fR \fIfunction\fR [\fB-f\fR] 
     [\fB-o\fR disable-at-boot | enable-at-boot] [\fB-n\fR | \fB-y\fR] sysctrl0:slot# ...
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR \fB-x\fR quiesce-test sysctrl0:slot# 
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR \fB-x\fR insert-test | remove-test sysctrl0:slot# ...
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR \fB-x\fR set-condition-test=# sysctrl0:slot# ...
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-l\fR]
     \fB-o\fR disable-at-boot | enable-at-boot sysctrl0:slot# ...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBsysctrl\fR hardware specific library
\fB/usr/platform/sun4u/lib/cfgadm/sysctrl.so.1\fR provides dynamic
reconfiguration functionality for configuring and disconnecting system boards
on \fBE6X00\fR, \fBE5X00\fR, \fBE4X00\fR, and \fBE3X00\fR systems. You can
insert both \fBI/O\fR and \fBCPU\fR boards into a slot on a running system that
is configured for Solaris without rebooting. You can also disconnect and remove
both types of boards from a running system without rebooting.
.sp
.LP
System slots appear as attachment points in the device tree, one attachment
point for each actual slot in the system chassis. If a board is not in a slot,
the receptacle state is \fBempty\fR. If a board is powered-off and ready to
remove, the receptacle state is \fBdisconnected\fR. If a board is powered-on
and is connected to the system bus, the receptacle state is \fBconnected\fR.
.sp
.LP
 The occupant state is \fBunconfigured\fR when the receptacle state is
\fBempty\fR or \fBdisconnected\fR. The occupant state is either
\fBunconfigured\fR or \fBconfigured\fR when the receptacle state is
\fBconnected\fR.
.sp
.LP
In the \fBconfigured\fR state the devices on a board are available for use by
Solaris. In the \fBunconfigured\fR state, the devices on the board are not.
.sp
.LP
Inserting a board changes the receptacle state from \fBempty\fR to
\fBdisconnected\fR. Removing a board changes the receptacle state from
\fBdisconnected\fR to \fBempty\fR. Removing a board that is in the
\fBconnected\fR state crashes the operating system and can result in permanent
damage to the system.
.SH OPTIONS
.sp
.LP
Refer to \fBcfgadm\fR(1M) for a more complete description options.
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-c\fR \fIfunction\fR\fR
.ad
.sp .6
.RS 4n
Perform the state change function. Specify \fIfunction\fR as \fBconnect\fR,
\fBdisconnect\fR, \fBconfigure\fR or \fBunconfigure\fR.
.sp
.ne 2
.mk
.na
\fBconfigure\fR
.ad
.RS 15n
.rt  
Change the occupant state to \fBconfigure\fR.
.sp
If the receptacle state is \fBdisconnect\fRed, the \fBconfigure\fR function
first attempts to connect the receptacle. The \fBconfigure\fR function walks
the \fBOBP\fR device tree created as part of the \fBconnect\fR function and
creates the Solaris device tree nodes, attaching devices as required. For
\fBCPU\fR/Memory boards, \fBconfigure\fR adds \fBCPU\fRs to the \fBCPU\fR list
in the \fBpowered-off \fRstate. These are visible to the \fBpsrinfo\fR(1M) and
\fBpsradm\fR(1M) commands. Two memory attachment points are published for
CPU/memory boards. Use \fBmount\fR(1M) and\fBifconfig\fR(1M) to use \fBI/O\fR
devices on the new board. To use \fBCPU\fRs, use \fBpsradm\fR \fB-n\fR to
on-line the new processors. Use \fBcfgadm_ac\fR(1M) to test and configure the
memory banks.
.RE

.sp
.ne 2
.mk
.na
\fBconnect\fR
.ad
.RS 15n
.rt  
Change the receptacle state to \fBconnect\fRed.
.sp
Changing the receptacle state requires that the system bus be frozen while the
bus signals are connected and the board tested. The bus is frozen by running a
\fBquiesce\fR operation which stops all process activity and suspends all
drivers. Because the \fBquiesce\fR operation and the subsequent resume can be
time consuming, and are not supported by all drivers, the \fB-x\fR
\fBquiesce-test\fR is provided. While the system bus is frozen, the board being
connected is tested by firmware. This operation takes a short time for
\fBI/O\fR boards and a significant time for \fBCPU\fR/Memory boards due to CPU
external cache testing. This does not provide memory testing. The user is
prompted for confirmation before proceeding with the \fBquiesce\fR. Use the
\fB-y\fR or \fB-n\fR option to override the prompt. The \fBconnect\fR operation
is refused if the board is marked as \fBdisabled-at-boot\fR, unless either the
force flag, \fB-f\fR, or the enable at boot flag, \fB-o\fR
\fBenable-at-boot\fR, is given. See \fB-l\fR.
.RE

.sp
.ne 2
.mk
.na
\fBdisconnect\fR
.ad
.RS 15n
.rt  
 Change the receptacle state to \fBdisconnect\fRed.
.sp
If the occupant state is \fBconfigure\fR, the \fBdisconnect\fR function first
attempts to unconfigure the occupant. The \fBdisconnect\fR operation does not
require a \fBquiesce\fR operation and operates quickly. The board is
powered-off ready for removal.
.RE

.sp
.ne 2
.mk
.na
\fBunconfigure\fR
.ad
.RS 15n
.rt  
Change the occupant state to \fBunconfigure\fRed.
.sp
Devices on the board are made invisible to Solaris during this process. The
\fBI/O\fR devices on an \fBI/O\fR board are removed from the Solaris device
tree. Any device that is still in use stops the unconfigure process and be
reported as in use. The unconfigure operation must be retried after the device
is made non-busy. For \fBCPU\fR/Memory boards, the memory must have been
changed to the unconfigured state prior to issuing the board unconfigure
operation. The \fBCPU\fRs on the board are off-lined, powered off and removed
from the Solaris \fBCPU\fR list. \fBCPU\fRs that have processes bound to them
cannot be off-lined. See \fBpsradm\fR(1M), \fBpsrinfo\fR(1M), \fBpbind\fR(1M),
and\fBp_online\fR(2) for more information on off-lining \fBCPU\fRs.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fB-f\fR\fR
.ad
.sp .6
.RS 4n
 Force a block on connecting a board marked as \fBdisabled-at-boot\fR in the
non-volatile \fBdisabled-board-list\fR variable. See \fIPlatform Notes:Sun
Enterprise 6x00/5x00/4x00/3x00 Systems\fR
.RE

.sp
.ne 2
.mk
.na
\fB\fB-l\fR\fR
.ad
.sp .6
.RS 4n
List options. Supported as described in \fBcfgadm\fR(1M)cfgadm(1M).
.sp
The \fItype\fR field can be one of \fBcpu/mem\fR, \fBmem\fR, \fBdual-sbus\fR,
\fBsbus-upa\fR, \fBdual-pci\fR, \fBsoc+sbus\fR, \fBsoc+upa\fR, \fBdisk\fR or
\fBunknown\fR.
.sp
The hardware-specific info field is set as follows:\fB [disabled at boot]
[non-detachable] [100 MHz capable] \fR
.sp
For \fBsbus-upa\fR and \fBsoc+upa\fR type boards, the following additional
information appears first: [\fBsingle buffered\fR \fBffb|double\fR
\fBbuffered\fR \fBffb|no\fR \fBffb installed\fR] For disk type boards, the
following additional information appears first: \fB{target: # | no disk}
{target: # | no disk}\fR
.RE

.sp
.ne 2
.mk
.na
\fB\fB-o\fR disable-at-boot | enable-at-boot\fR
.ad
.sp .6
.RS 4n
Modify the state of the non\(emvolatile \fB disabled-board-list\fR variable.
Use this the \fB-o\fR option in conjunction with the \fB-c\fR \fIfunction\fR or
\fB-l\fR option.
.sp
Use \fB-o\fR \fBenable-at-boot\fR with the \fB-c\fR \fBconnect\fR to override a
block on connecting a \fBdisabled-at-boot\fR board.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-x\fR insert-test | remove-test\fR
.ad
.sp .6
.RS 4n
Perform a test.
.sp
 Specify \fBremove-test\fR to change the driver state for the specified slot
from \fBdisconnected\fR to \fBempty\fR without the need for physically removing
the board during automated test sequences.
.sp
Specify \fBinsert-test\fR to change the driver state of a slot made to appear
empty using the \fBremove-test\fR command to the d\fBisconnected\fR state as if
it had been inserted.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-x\fR quiesce-test sysctrl0:slot1\fR
.ad
.sp .6
.RS 4n
Perform a test.
.sp
Allows the \fBquiesce\fR operation required for board connect operations to be
exercised. The execution of this test confirms that, with the current software
and hardware configuration, it is possible to quiesce the system. If a device
or process cannot be quiesced, its name is printed in an error message. Any
valid board attachment point can be used with this command, but since all
systems have a slot1 the given form is recommended.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-x\fR set-condition-test=# \fR
.ad
.sp .6
.RS 4n
Perform a test.
.sp
Allows the condition of a system board attachment point to be set for testing
the policy logic for state change commands. The new setting is given as a
number indicating one of the following condition values:
.sp
.in +2
.nf
0      unknown
1      ok 
2      failing
3      failed
4      unusable
.fi
.in -2
.sp

.RE

.SH OPERANDS
.sp
.LP
The following operand is supported:
.sp
.ne 2
.mk
.na
\fBsysctrl0:slot\fI#\fR\fR
.ad
.RS 28n
.rt  
The attachment points for boards on \fBEXX00\fR systems are published by
instance \fB0\fR of the \fBsysctrl\fR driver (\fBsysctrl0\fR). The names of the
attachment points are numbered from \fBslot0\fR through \fBslot15\fR. Specify
\fI#\fR as a number between \fB0\fR and \fB15\fR, indicating the slot number.
This form conforms to the logical \fBap_id\fR specification given in
\fBcfgadm\fR(1M). The corresponding physical \fBap_id\fRs are listed in the
\fBFILES\fR section.
.RE

.SH FILES
.sp
.ne 2
.mk
.na
\fB/usr/platform/sun4u/lib/cfgadm/sysctrl.so.1\fR
.ad
.sp .6
.RS 4n
Hardware specific library
.RE

.sp
.ne 2
.mk
.na
\fB/devices/central@1f,0/fhc@0,f8800000/clock-board@0,900000:slot*\fR
.ad
.sp .6
.RS 4n
Attachment Points
.RE

.SH SEE ALSO
.sp
.LP
\fBcfgadm\fR(1M), \fBcfgadm_ac\fR(1M), \fBifconfig\fR(1M), \fBmount\fR(1M),
\fBpbind\fR(1M), \fBpsradm\fR(1M), , \fBpsrinfo\fR(1M),
\fBconfig_admin\fR(3CFGADM), \fBattributes\fR(5)
.sp
.LP
\fISun Enterprise 6x00, 5x00, 4x00 and 3x00 Systems Dynamic Reconfiguration
User's Guide\fR
.sp
.LP
\fIPlatform Notes:Sun Enterprise 6x00/5x00/4x00/3x00 Systems\fR
.SH NOTES
.sp
.LP
Refer to the \fISun Enterprise 6x00, 5x00, 4x00 and 3x00 Systems Dynamic
Reconfiguration User's Guide\fR for additional details regarding dynamic
reconfiguration of EXX00 system CPU/Memory boards.