1 '\" te
2 .\" Copyright (c) 1999 Sun Microsystems, Inc. All Rights Reserved.
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH CFGADM_SYSCTRL 1M "Mar 10, 1999"
7 .SH NAME
8 cfgadm_sysctrl \- EXX00 system board administration
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/sbin/cfgadm\fR \fB-c\fR \fIfunction\fR [\fB-f\fR]
13 [\fB-o\fR disable-at-boot | enable-at-boot] [\fB-n\fR | \fB-y\fR] sysctrl0:slot# ...
14 .fi
15
16 .LP
17 .nf
18 \fB/usr/sbin/cfgadm\fR \fB-x\fR quiesce-test sysctrl0:slot#
19 .fi
20
21 .LP
22 .nf
23 \fB/usr/sbin/cfgadm\fR \fB-x\fR insert-test | remove-test sysctrl0:slot# ...
24 .fi
25
26 .LP
27 .nf
28 \fB/usr/sbin/cfgadm\fR \fB-x\fR set-condition-test=# sysctrl0:slot# ...
29 .fi
30
31 .LP
32 .nf
33 \fB/usr/sbin/cfgadm\fR [\fB-l\fR]
34 \fB-o\fR disable-at-boot | enable-at-boot sysctrl0:slot# ...
35 .fi
36
37 .SH DESCRIPTION
38 .sp
39 .LP
40 The \fBsysctrl\fR hardware specific library
41 \fB/usr/platform/sun4u/lib/cfgadm/sysctrl.so.1\fR provides dynamic
42 reconfiguration functionality for configuring and disconnecting system boards
43 on \fBE6X00\fR, \fBE5X00\fR, \fBE4X00\fR, and \fBE3X00\fR systems. You can
44 insert both \fBI/O\fR and \fBCPU\fR boards into a slot on a running system that
45 is configured for Solaris without rebooting. You can also disconnect and remove
46 both types of boards from a running system without rebooting.
47 .sp
48 .LP
49 System slots appear as attachment points in the device tree, one attachment
50 point for each actual slot in the system chassis. If a board is not in a slot,
51 the receptacle state is \fBempty\fR. If a board is powered-off and ready to
52 remove, the receptacle state is \fBdisconnected\fR. If a board is powered-on
53 and is connected to the system bus, the receptacle state is \fBconnected\fR.
54 .sp
55 .LP
56 The occupant state is \fBunconfigured\fR when the receptacle state is
57 \fBempty\fR or \fBdisconnected\fR. The occupant state is either
58 \fBunconfigured\fR or \fBconfigured\fR when the receptacle state is
59 \fBconnected\fR.
60 .sp
61 .LP
62 In the \fBconfigured\fR state the devices on a board are available for use by
63 Solaris. In the \fBunconfigured\fR state, the devices on the board are not.
64 .sp
65 .LP
66 Inserting a board changes the receptacle state from \fBempty\fR to
67 \fBdisconnected\fR. Removing a board changes the receptacle state from
68 \fBdisconnected\fR to \fBempty\fR. Removing a board that is in the
69 \fBconnected\fR state crashes the operating system and can result in permanent
70 damage to the system.
71 .SH OPTIONS
72 .sp
73 .LP
74 Refer to \fBcfgadm\fR(1M) for a more complete description options.
75 .sp
76 .LP
77 The following options are supported:
78 .sp
79 .ne 2
80 .na
81 \fB\fB-c\fR \fIfunction\fR\fR
82 .ad
83 .sp .6
84 .RS 4n
85 Perform the state change function. Specify \fIfunction\fR as \fBconnect\fR,
86 \fBdisconnect\fR, \fBconfigure\fR or \fBunconfigure\fR.
87 .sp
88 .ne 2
89 .na
90 \fBconfigure\fR
91 .ad
92 .RS 15n
93 Change the occupant state to \fBconfigure\fR.
94 .sp
95 If the receptacle state is \fBdisconnect\fRed, the \fBconfigure\fR function
96 first attempts to connect the receptacle. The \fBconfigure\fR function walks
97 the \fBOBP\fR device tree created as part of the \fBconnect\fR function and
98 creates the Solaris device tree nodes, attaching devices as required. For
99 \fBCPU\fR/Memory boards, \fBconfigure\fR adds \fBCPU\fRs to the \fBCPU\fR list
100 in the \fBpowered-off \fRstate. These are visible to the \fBpsrinfo\fR(1M) and
101 \fBpsradm\fR(1M) commands. Two memory attachment points are published for
102 CPU/memory boards. Use \fBmount\fR(1M) and \fBifconfig\fR(1M) to use \fBI/O\fR
103 devices on the new board. To use \fBCPU\fRs, use \fBpsradm\fR \fB-n\fR to
104 on-line the new processors. Use \fBcfgadm_ac\fR(1M) to test and configure the
105 memory banks.
106 .RE
107
108 .sp
109 .ne 2
110 .na
111 \fBconnect\fR
112 .ad
113 .RS 15n
114 Change the receptacle state to \fBconnect\fRed.
115 .sp
116 Changing the receptacle state requires that the system bus be frozen while the
117 bus signals are connected and the board tested. The bus is frozen by running a
118 \fBquiesce\fR operation which stops all process activity and suspends all
119 drivers. Because the \fBquiesce\fR operation and the subsequent resume can be
120 time consuming, and are not supported by all drivers, the \fB-x\fR
121 \fBquiesce-test\fR is provided. While the system bus is frozen, the board being
122 connected is tested by firmware. This operation takes a short time for
123 \fBI/O\fR boards and a significant time for \fBCPU\fR/Memory boards due to CPU
124 external cache testing. This does not provide memory testing. The user is
125 prompted for confirmation before proceeding with the \fBquiesce\fR. Use the
126 \fB-y\fR or \fB-n\fR option to override the prompt. The \fBconnect\fR operation
127 is refused if the board is marked as \fBdisabled-at-boot\fR, unless either the
128 force flag, \fB-f\fR, or the enable at boot flag, \fB-o\fR
129 \fBenable-at-boot\fR, is given. See \fB-l\fR.
130 .RE
131
132 .sp
133 .ne 2
134 .na
135 \fBdisconnect\fR
136 .ad
137 .RS 15n
138 Change the receptacle state to \fBdisconnect\fRed.
139 .sp
140 If the occupant state is \fBconfigure\fR, the \fBdisconnect\fR function first
141 attempts to unconfigure the occupant. The \fBdisconnect\fR operation does not
142 require a \fBquiesce\fR operation and operates quickly. The board is
143 powered-off ready for removal.
144 .RE
145
146 .sp
147 .ne 2
148 .na
149 \fBunconfigure\fR
150 .ad
151 .RS 15n
152 Change the occupant state to \fBunconfigure\fRed.
153 .sp
154 Devices on the board are made invisible to Solaris during this process. The
155 \fBI/O\fR devices on an \fBI/O\fR board are removed from the Solaris device
156 tree. Any device that is still in use stops the unconfigure process and be
157 reported as in use. The unconfigure operation must be retried after the device
158 is made non-busy. For \fBCPU\fR/Memory boards, the memory must have been
159 changed to the unconfigured state prior to issuing the board unconfigure
160 operation. The \fBCPU\fRs on the board are off-lined, powered off and removed
161 from the Solaris \fBCPU\fR list. \fBCPU\fRs that have processes bound to them
162 cannot be off-lined. See \fBpsradm\fR(1M), \fBpsrinfo\fR(1M), \fBpbind\fR(1M),
163 and \fBp_online\fR(2) for more information on off-lining \fBCPU\fRs.
164 .RE
165
166 .RE
167
168 .sp
169 .ne 2
170 .na
171 \fB\fB-f\fR\fR
172 .ad
173 .sp .6
174 .RS 4n
175 Force a block on connecting a board marked as \fBdisabled-at-boot\fR in the
176 non-volatile \fBdisabled-board-list\fR variable. See \fIPlatform Notes:Sun
177 Enterprise 6x00/5x00/4x00/3x00 Systems\fR
178 .RE
179
180 .sp
181 .ne 2
182 .na
183 \fB\fB-l\fR\fR
184 .ad
185 .sp .6
186 .RS 4n
187 List options. Supported as described in \fBcfgadm\fR(1M)cfgadm(1M).
188 .sp
189 The \fItype\fR field can be one of \fBcpu/mem\fR, \fBmem\fR, \fBdual-sbus\fR,
190 \fBsbus-upa\fR, \fBdual-pci\fR, \fBsoc+sbus\fR, \fBsoc+upa\fR, \fBdisk\fR or
191 \fBunknown\fR.
192 .sp
193 The hardware-specific info field is set as follows:\fB [disabled at boot]
194 [non-detachable] [100 MHz capable] \fR
195 .sp
196 For \fBsbus-upa\fR and \fBsoc+upa\fR type boards, the following additional
197 information appears first: [\fBsingle buffered\fR \fBffb|double\fR
198 \fBbuffered\fR \fBffb|no\fR \fBffb installed\fR] For disk type boards, the
199 following additional information appears first: \fB{target: # | no disk}
200 {target: # | no disk}\fR
201 .RE
202
203 .sp
204 .ne 2
205 .na
206 \fB\fB-o\fR disable-at-boot | enable-at-boot\fR
207 .ad
208 .sp .6
209 .RS 4n
210 Modify the state of the non\(emvolatile \fB disabled-board-list\fR variable.
211 Use this the \fB-o\fR option in conjunction with the \fB-c\fR \fIfunction\fR or
212 \fB-l\fR option.
213 .sp
214 Use \fB-o\fR \fBenable-at-boot\fR with the \fB-c\fR \fBconnect\fR to override a
215 block on connecting a \fBdisabled-at-boot\fR board.
216 .RE
217
218 .sp
219 .ne 2
220 .na
221 \fB\fB-x\fR insert-test | remove-test\fR
222 .ad
223 .sp .6
224 .RS 4n
225 Perform a test.
226 .sp
227 Specify \fBremove-test\fR to change the driver state for the specified slot
228 from \fBdisconnected\fR to \fBempty\fR without the need for physically removing
229 the board during automated test sequences.
230 .sp
231 Specify \fBinsert-test\fR to change the driver state of a slot made to appear
232 empty using the \fBremove-test\fR command to the d\fBisconnected\fR state as if
233 it had been inserted.
234 .RE
235
236 .sp
237 .ne 2
238 .na
239 \fB\fB-x\fR quiesce-test sysctrl0:slot1\fR
240 .ad
241 .sp .6
242 .RS 4n
243 Perform a test.
244 .sp
245 Allows the \fBquiesce\fR operation required for board connect operations to be
246 exercised. The execution of this test confirms that, with the current software
247 and hardware configuration, it is possible to quiesce the system. If a device
248 or process cannot be quiesced, its name is printed in an error message. Any
249 valid board attachment point can be used with this command, but since all
250 systems have a slot1 the given form is recommended.
251 .RE
252
253 .sp
254 .ne 2
255 .na
256 \fB\fB-x\fR set-condition-test=# \fR
257 .ad
258 .sp .6
259 .RS 4n
260 Perform a test.
261 .sp
262 Allows the condition of a system board attachment point to be set for testing
263 the policy logic for state change commands. The new setting is given as a
264 number indicating one of the following condition values:
265 .sp
266 .in +2
267 .nf
268 0 unknown
269 1 ok
270 2 failing
271 3 failed
272 4 unusable
273 .fi
274 .in -2
275 .sp
276
277 .RE
278
279 .SH OPERANDS
280 .sp
281 .LP
282 The following operand is supported:
283 .sp
284 .ne 2
285 .na
286 \fBsysctrl0:slot\fI#\fR\fR
287 .ad
288 .RS 28n
289 The attachment points for boards on \fBEXX00\fR systems are published by
290 instance \fB0\fR of the \fBsysctrl\fR driver (\fBsysctrl0\fR). The names of the
291 attachment points are numbered from \fBslot0\fR through \fBslot15\fR. Specify
292 \fI#\fR as a number between \fB0\fR and \fB15\fR, indicating the slot number.
293 This form conforms to the logical \fBap_id\fR specification given in
294 \fBcfgadm\fR(1M). The corresponding physical \fBap_id\fRs are listed in the
295 \fBFILES\fR section.
296 .RE
297
298 .SH FILES
299 .sp
300 .ne 2
301 .na
302 \fB/usr/platform/sun4u/lib/cfgadm/sysctrl.so.1\fR
303 .ad
304 .sp .6
305 .RS 4n
306 Hardware specific library
307 .RE
308
309 .sp
310 .ne 2
311 .na
312 \fB/devices/central@1f,0/fhc@0,f8800000/clock-board@0,900000:slot*\fR
313 .ad
314 .sp .6
315 .RS 4n
316 Attachment Points
317 .RE
318
319 .SH SEE ALSO
320 .sp
321 .LP
322 \fBcfgadm\fR(1M), \fBcfgadm_ac\fR(1M), \fBifconfig\fR(1M), \fBmount\fR(1M),
323 \fBpbind\fR(1M), \fBpsradm\fR(1M), , \fBpsrinfo\fR(1M),
324 \fBconfig_admin\fR(3CFGADM), \fBattributes\fR(5)
325 .sp
326 .LP
327 \fISun Enterprise 6x00, 5x00, 4x00 and 3x00 Systems Dynamic Reconfiguration
328 User's Guide\fR
329 .sp
330 .LP
331 \fIPlatform Notes:Sun Enterprise 6x00/5x00/4x00/3x00 Systems\fR
332 .SH NOTES
333 .sp
334 .LP
335 Refer to the \fISun Enterprise 6x00, 5x00, 4x00 and 3x00 Systems Dynamic
336 Reconfiguration User's Guide\fR for additional details regarding dynamic
337 reconfiguration of EXX00 system CPU/Memory boards.