| blob | 78a1d5c5b939ec4bfeaca3f4bbebee57db6d39b8 |
1 '\" te
2 .\" Copyright (c) 2003 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_SCSI 8 "Jun 6, 2006"
7 .SH NAME
8 cfgadm_scsi \- SCSI hardware specific commands for cfgadm
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR] [\fB-o\fR \fIhardware_option\fR]
13 \fB-c\fR \fIfunction\fR \fIap_id\fR...
14 .fi
16 .LP
17 .nf
18 \fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR] [\fB-o\fR \fIhardware_option\fR]
19 \fB-x\fR \fIhardware_function\fR \fIap_id\fR...
20 .fi
22 .LP
23 .nf
24 \fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-a\fR] [\fB-s\fR\fI listing_option\fR] [\fB-o\fR \fIhardware_option\fR]
25 [\fB-l\fR [\fIap_id\fR | \fIap_type ...\fR ]]
26 .fi
28 .LP
29 .nf
30 \fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-o\fR\fI hardware_option\fR] \fB-t\fR \fIap_id\fR...
31 .fi
33 .LP
34 .nf
35 \fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-o\fR\fI hardware_option\fR] \fB-h\fR [\fIap_id\fR]...
36 .fi
38 .SH DESCRIPTION
39 .sp
40 .LP
41 The \fBSCSI\fR hardware specific library \fB/usr/lib/cfgadm/scsi.so.1\fR
42 provides the functionality for \fBSCSI\fR hot-plugging through the
43 \fBcfgadm\fR(8) command. \fBcfgadm\fR operates on attachment points, which are
44 locations in the system where hardware resources can be dynamically
45 reconfigured. Refer to \fBcfgadm\fR(8) for information regarding attachment
46 points.
47 .sp
48 .LP
49 For \fBSCSI\fR hot-plugging, each \fBSCSI\fR controller is represented by an
50 attachment point in the device tree. In addition, each \fBSCSI \fRdevice is
51 represented by a dynamic attachment point. Attachment points are named through
52 \fBap_ids\fR. Two types of \fBap_ids\fR are defined: logical and physical. The
53 physical \fBap_id\fR is based on the physical pathname, whereas the logical
54 \fBap_id\fR is a shorter more user-friendly name. For \fBSCSI \fRcontrollers,
55 the logical \fBap_id\fR is usually the corresponding disk controller number.
56 For example, a typical logical \fBap_id\fR would be \fBc0\fR.
57 .sp
58 .LP
59 \fBSCSI\fR devices are named relative to the controller \fBap_id\fR. Thus if a
60 disk device is attached to controller \fBc0\fR, its \fBap_id\fR can be:
61 .sp
62 .in +2
63 .nf
64 c0::dsk/c0t0d0
65 .fi
66 .in -2
67 .sp
69 .sp
70 .LP
71 where \fBdsk/c0t0d0\fR identifies the specific device. In general, the device
72 identifier is derived from the corresponding logical link for the device in
73 \fB/dev\fR. For example, a \fBSCSI\fR tape drive logical \fBap_id\fR could be
74 \fBc0::rmt/0\fR. Here \fBc0\fR is the logical \fBap_id\fR for the \fBSCSI\fR
75 controller and \fBrmt/0\fR is derived from the logical link for the tape drive
76 in \fB/dev/rmt\fR. If an identifier can not be derived from the link in
77 \fB/dev\fR, a unique identifier will be assigned to it. For example, if the
78 tape device has no link in \fB/dev\fR, it can be assigned an \fBap_id\fR of the
79 form \fBc0::st3\fR where \fBst3\fR is a unique internally generated identifier.
80 .sp
81 .LP
82 A simple listing of attachment points in the system will include attachment
83 points at \fBSCSI \fRcontrollers but not \fBSCSI\fR devices. Use the \fB-a\fR
84 flag to the list option (\fB-l\fR) to list \fBSCSI\fR devices as well. For
85 example:
86 .sp
87 .in +2
88 .nf
89 # cfgadm -l
90 Ap_Id Type Receptacle Occupant Condition
91 c0 scsi-bus connected configured unknown
92 sysctrl0:slot0 cpu/mem connected configured ok
93 sysctrl0:slot1 sbus-upa connected configured ok
94 .fi
95 .in -2
96 .sp
98 .sp
99 .LP
100 To list \fBSCSI\fR devices in addition to \fBSCSI\fR controllers:
101 .sp
102 .in +2
103 .nf
104 # cfgadm -al
106 Ap_Id Type Receptacle Occupant Condition
107 c0 scsi-bus connected configured unknown
108 c0::dsk/c0t14d0 disk connected configured unknown
109 c0::dsk/c0t11d0 disk connected configured unknown
110 c0::dsk/c0t8d0 disk connected configured unknown
111 c0::dsk/c0t0d0 disk connected configured unknown
112 c0::rmt/0 tape connected configured unknown
113 sysctrl0:slot0 cpu/mem connected configured ok
114 sysctrl0:slot1 sbus-upa connected configured ok
115 .fi
116 .in -2
117 .sp
119 .sp
120 .LP
121 Refer to \fBcfgadm\fR(8) for more information regarding listing attachment
122 points. The receptacle and occupant state for attachment points at the
123 \fBSCSI\fR controller have the following meanings:
124 .sp
125 .ne 2
126 .na
127 \fBempty\fR
128 .ad
129 .RS 16n
130 not applicable
131 .RE
133 .sp
134 .ne 2
135 .na
136 \fBdisconnected\fR
137 .ad
138 .RS 16n
139 bus quiesced (\fBI/O\fR activity on bus is suspended)
140 .RE
142 .sp
143 .ne 2
144 .na
145 \fBconnected\fR
146 .ad
147 .RS 16n
148 bus active
149 .RE
151 .sp
152 .ne 2
153 .na
154 \fBconfigured\fR
155 .ad
156 .RS 16n
157 one or more devices on the bus is configured
158 .RE
160 .sp
161 .ne 2
162 .na
163 \fBunconfigured\fR
164 .ad
165 .RS 16n
166 no device on the bus is configured
167 .RE
169 .sp
170 .LP
171 The corresponding states for individual \fBSCSI\fR devices are:
172 .sp
173 .ne 2
174 .na
175 \fBempty\fR
176 .ad
177 .RS 16n
178 not applicable
179 .RE
181 .sp
182 .ne 2
183 .na
184 \fBdisconnected\fR
185 .ad
186 .RS 16n
187 bus to which the device is attached is quiesced
188 .RE
190 .sp
191 .ne 2
192 .na
193 \fBconnected\fR
194 .ad
195 .RS 16n
196 bus to which device is attached is active
197 .RE
199 .sp
200 .ne 2
201 .na
202 \fBconfigured\fR
203 .ad
204 .RS 16n
205 device is configured
206 .RE
208 .sp
209 .ne 2
210 .na
211 \fBunconfigured\fR
212 .ad
213 .RS 16n
214 device is not configured
215 .RE
217 .SH OPTIONS
218 .sp
219 .LP
220 \fBcfgadm\fR defines several types of operations besides listing
221 (\fB-l\fR).These operations include testing, (\fB-t\fR), invoking configuration
222 state changes, (\fB-c\fR), invoking hardware specific functions (\fB-x\fR), and
223 obtaining configuration administration help messages (\fB-h\fR).
224 .sp
225 .ne 2
226 .na
227 \fB\fB-c\fR \fIfunction\fR\fR
228 .ad
229 .RS 24n
230 The following generic commands are defined for the \fBSCSI \fRhardware specific
231 library:
232 .sp
233 For \fBSCSI\fR controller attachment points, the following configuration state
234 change operations are supported:
235 .sp
236 .ne 2
237 .na
238 \fBconnect\fR
239 .ad
240 .RS 15n
241 Unquiesce the \fBSCSI\fR bus.
242 .RE
244 .sp
245 .ne 2
246 .na
247 \fBdisconnect\fR
248 .ad
249 .RS 15n
250 Quiesce the bus (suspend \fBI/O\fR activity on bus).
251 .sp
252 Incorrect use of this command can cause the system to hang. See \fBNOTES\fR.
253 .RE
255 .sp
256 .ne 2
257 .na
258 \fBconfigure\fR
259 .ad
260 .RS 15n
261 Configure new devices on \fBSCSI\fR bus.
262 .RE
264 .sp
265 .ne 2
266 .na
267 \fBunconfigure\fR
268 .ad
269 .RS 15n
270 Unconfigure all devices connected to bus.
271 .RE
273 The following generic commands are defined for \fBSCSI\fR devices:
274 .sp
275 .ne 2
276 .na
277 \fBconfigure\fR
278 .ad
279 .RS 15n
280 configure a specific device
281 .RE
283 .sp
284 .ne 2
285 .na
286 \fBunconfigure\fR
287 .ad
288 .RS 15n
289 unconfigure a specific device
290 .RE
292 .RE
294 .sp
295 .ne 2
296 .na
297 \fB\fB-f\fR\fR
298 .ad
299 .RS 24n
300 When used with the \fBdisconnect\fR command, forces a quiesce of the \fBSCSI\fR
301 bus, if supported by hardware.
302 .sp
303 Incorrect use of this command can cause the system to hang. See \fBNOTES\fR.
304 .RE
306 .sp
307 .ne 2
308 .na
309 \fB\fB-h\fR \fIap_id\fR\fR
310 .ad
311 .RS 24n
312 SCSI specific help can be obtained by using the help option with any SCSI
313 attachment point.
314 .RE
316 .sp
317 .ne 2
318 .na
319 \fB\fB-o\fR \fIhardware_option\fR\fR
320 .ad
321 .RS 24n
322 No hardware specific options are currently defined.
323 .RE
325 .sp
326 .ne 2
327 .na
328 \fB\fB-s\fR \fIlisting_option\fR\fR
329 .ad
330 .RS 24n
331 Attachment points of class \fBscsi\fR can be listed by using the \fBselect\fR
332 sub-option. Refer to the \fBcfgadm\fR(8) man page for additional information.
333 .RE
335 .sp
336 .ne 2
337 .na
338 \fB\fB-t\fR \fIap_id\fR\fR
339 .ad
340 .RS 24n
341 No test commands are available at present.
342 .RE
344 .sp
345 .ne 2
346 .na
347 \fB\fB-x\fR \fIhardware_function\fR\fR
348 .ad
349 .RS 24n
350 Some of the following commands can only be used with SCSI controllers and some
351 only with SCSI devices.
352 .sp
353 In the following, \fIcontroller_ap_id\fR refers to an \fBap_id\fR for a SCSI
354 controller, for example, \fBc0\fR. \fIdevice_ap_id\fR refers to an \fBap_id\fR
355 for a \fBSCSI\fR device, for example: \fBc0::dsk/c0dt3d0\fR.
356 .sp
357 The following hardware specific functions are defined:
358 .sp
359 .ne 2
360 .na
361 \fBinsert_device \fIcontroller_ap_id\fR\fR
362 .ad
363 .sp .6
364 .RS 4n
365 Add a new device to the SCSI controller, \fIcontroller_ap_id\fR.
366 .sp
367 This command is intended for interactive use only.
368 .RE
370 .sp
371 .ne 2
372 .na
373 \fBremove_device \fIdevice_ap_id\fR\fR
374 .ad
375 .sp .6
376 .RS 4n
377 Remove device \fIdevice_ap_id\fR.
378 .sp
379 This command is intended for interactive use only.
380 .RE
382 .sp
383 .ne 2
384 .na
385 \fBreplace_device \fIdevice_ap_id\fR\fR
386 .ad
387 .sp .6
388 .RS 4n
389 Remove device \fIdevice_ap_id\fR and replace it with another device of the same
390 kind.
391 .sp
392 This command is intended for interactive use only.
393 .RE
395 .sp
396 .ne 2
397 .na
398 \fBreset_device \fIdevice_ap_id\fR\fR
399 .ad
400 .sp .6
401 .RS 4n
402 Reset \fIdevice_ap_id\fR.
403 .RE
405 .sp
406 .ne 2
407 .na
408 \fBreset_bus \fIcontroller_ap_id\fR\fR
409 .ad
410 .sp .6
411 .RS 4n
412 Reset bus \fIcontroller_ap_id\fR without resetting any devices attached to the
413 bus.
414 .RE
416 .sp
417 .ne 2
418 .na
419 \fBreset_all \fIcontroller_ap_id\fR\fR
420 .ad
421 .sp .6
422 .RS 4n
423 Reset bus \fIcontroller_ap_id\fR and all devices on the bus.
424 .RE
426 .sp
427 .ne 2
428 .na
429 \fBlocator [=on|off] \fIdevice_ap_id\fR\fR
430 .ad
431 .sp .6
432 .RS 4n
433 Sets or gets the hard disk locator \fBLED\fR, if it is provided by the
434 platform. If the [on|off] suboption is not set, the state of the hard disk
435 locator is printed.
436 .RE
438 .sp
439 .ne 2
440 .na
441 \fBled[=LED,mode=on|off|blink] \fIdevice_ap_id\fR\fR
442 .ad
443 .sp .6
444 .RS 4n
445 If no sub-arguments are set, this function print a list of the current
446 \fBLED\fR settings. If sub-arguments are set, this function sets the mode of a
447 specific \fBLED\fR for a slot.
448 .RE
450 .RE
452 .SH EXAMPLES
453 .LP
454 \fBExample 1 \fRConfiguring a Disk
455 .sp
456 .LP
457 The following command configures a disk attached to controller \fBc0\fR:
459 .sp
460 .in +2
461 .nf
462 # \fBcfgadm -c configure c0::dsk/c0t3d0\fR
463 .fi
464 .in -2
465 .sp
467 .LP
468 \fBExample 2 \fRUnconfiguring a Disk
469 .sp
470 .LP
471 The following command unconfigures a disk attached to controller \fBc0\fR:
473 .sp
474 .in +2
475 .nf
476 # \fBcfgadm -c unconfigure c0::dsk/c0t3d0\fR
477 .fi
478 .in -2
479 .sp
481 .LP
482 \fBExample 3 \fRAdding a New Device
483 .sp
484 .LP
485 The following command adds a new device to controller \fBc0\fR:
487 .sp
488 .in +2
489 .nf
490 # \fBcfgadm -x insert_device c0\fR
491 .fi
492 .in -2
493 .sp
495 .sp
496 .LP
497 The system responds with the following:
499 .sp
500 .in +2
501 .nf
502 Adding device to SCSI HBA: /devices/sbus@1f,0/SUNW,fas@e,8800000
503 This operation will suspend activity on SCSI bus c0
504 Continue (yes/no)?
505 .fi
506 .in -2
507 .sp
509 .sp
510 .LP
511 Enter:
513 .sp
514 .in +2
515 .nf
516 \fBy\fR
517 .fi
518 .in -2
519 .sp
521 .sp
522 .LP
523 The system responds with the following:
525 .sp
526 .in +2
527 .nf
528 SCSI bus quiesced successfully.
529 It is now safe to proceed with hotplug operation.
530 Enter y if operation is complete or n to abort (yes/no)?
531 .fi
532 .in -2
533 .sp
535 .sp
536 .LP
537 Enter:
539 .sp
540 .in +2
541 .nf
542 \fBy\fR
543 .fi
544 .in -2
545 .sp
547 .LP
548 \fBExample 4 \fRReplacing a Device
549 .sp
550 .LP
551 The following command replaces a device attached to controller \fBc0\fR:
553 .sp
554 .in +2
555 .nf
556 # \fBcfgadm \fR\fB-x\fR\fB replace_device c0::dsk/c0t3d0\fR
557 .fi
558 .in -2
559 .sp
561 .sp
562 .LP
563 The system responds with the following:
565 .sp
566 .in +2
567 .nf
568 Replacing SCSI device: /devices/sbus@1f,0/SUNW,fas@e,8800000/sd@3,0
569 This operation will suspend activity on SCSI bus: c0
570 Continue (yes/no)?
571 .fi
572 .in -2
573 .sp
575 .sp
576 .LP
577 Enter:
579 .sp
580 .in +2
581 .nf
582 \fBy\fR
583 .fi
584 .in -2
585 .sp
587 .sp
588 .LP
589 The system responds with the following:
591 .sp
592 .in +2
593 .nf
594 SCSI bus quiesced successfully.
595 It is now safe to proceed with hotplug operation.
596 Enter y if operation is complete or n to abort (yes/no)?
597 .fi
598 .in -2
599 .sp
601 .sp
602 .LP
603 Enter:
605 .sp
606 .in +2
607 .nf
608 \fBy\fR
609 .fi
610 .in -2
611 .sp
613 .LP
614 \fBExample 5 \fREncountering a Mounted File System While Unconfiguring a Disk
615 .sp
616 .LP
617 The following command illustrates encountering a mounted file system while
618 unconfiguring a disk:
620 .sp
621 .in +2
622 .nf
623 # \fBcfgadm -c unconfigure c1::dsk/c1t0d0\fR
624 .fi
625 .in -2
626 .sp
628 .sp
629 .LP
630 The system responds with the following:
632 .sp
633 .in +2
634 .nf
635 cfgadm: Component system is busy, try again: failed to offline:
636 /devices/pci@1f,4000/scsi@3,1/sd@1,0
637 Resource Information
638 ------------------ --------------------------
639 /dev/dsk/c1t0d0s0 mounted filesystem "/mnt"
640 .fi
641 .in -2
642 .sp
644 .LP
645 \fBExample 6 \fRDisplay the Value of the Locator for a Disk
646 .sp
647 .LP
648 The following command displays the value of the locator for a disk. This
649 example is specific to the \fBSPARC\fR Enterprise Server family:
651 .sp
652 .in +2
653 .nf
654 # \fBcfgadm -x locator c0::dsk/c0t6d0\fR
655 .fi
656 .in -2
657 .sp
659 .sp
660 .LP
661 The system responds with the following:
663 .sp
664 .in +2
665 .nf
666 Disk Led
667 c0t6d0 locator=on
668 .fi
669 .in -2
670 .sp
672 .LP
673 \fBExample 7 \fRSet the Value of the Locator for a Disk
674 .sp
675 .LP
676 The following command sets the value of the locator for a disk. This example is
677 specific to the \fBSPARC\fR Enterprise Server family:
679 .sp
680 .in +2
681 .nf
682 # \fBcfgadm -x locator=off c0::dsk/c0t6d0\fR
683 .fi
684 .in -2
685 .sp
687 .sp
688 .LP
689 The system does not print anything in response.
691 .SH FILES
692 .sp
693 .ne 2
694 .na
695 \fB\fB/usr/lib/cfgadm/scsi.so.1\fR\fR
696 .ad
697 .sp .6
698 .RS 4n
699 hardware-specific library for generic \fBSCSI\fR hot-plugging
700 .RE
702 .sp
703 .ne 2
704 .na
705 \fB\fB/usr/platform/SPARC-Enterprise/lib/cfgadm/scsi.so.1\fR\fR
706 .ad
707 .sp .6
708 .RS 4n
709 platform-specific library for generic \fBSCSI\fR hot-plugging
710 .RE
712 .SH SEE ALSO
713 .sp
714 .LP
715 \fBcfgadm\fR(8), \fBluxadm\fR(8), \fBconfig_admin\fR(3CFGADM),
716 \fBlibcfgadm\fR(3LIB), \fBattributes\fR(5)
717 .SH NOTES
718 .sp
719 .LP
720 The \fBdisconnect\fR (quiesce) operation is not supported on controllers which
721 control disks containing critical partitions such as \fBroot\fR (\fB/\fR),
722 \fB/usr\fR, \fBswap\fR, or \fB/var\fR. The \fBdisconnect\fR operation should
723 not be attempted on such controllers. Incorrect usage can result in a system
724 hang and require a reboot.
725 .sp
726 .LP
727 When a controller is in the disconnected (quiesced) state, there is a potential
728 for deadlocks occurring in the system. The \fBdisconnect\fR operation should be
729 used with caution. A controller should be kept in the disconnected state for
730 the minimum period of time required to accomplish the \fBDR\fR operation. The
731 \fBdisconnect\fR command is provided only to allow the replacement of the
732 \fBSCSI\fR cables while the system is running. It should not be used for any
733 other purpose. The only fix for a deadlock (if it occurs) is to reboot the
734 system.
735 .sp
736 .LP
737 Hotplugging operations are not supported by all \fBSCSI\fR controllers.
738 .SH WARNINGS
739 .sp
740 .LP
741 The connectors on some \fBSCSI\fR devices do not conform to \fBSCSI\fR hotplug
742 specifications. Performing hotplug operations on such devices can cause damage
743 to the hardware on the \fBSCSI\fR bus. Refer to your hardware manual for
744 additional information.