| blob | cea13c7f0f3a049cf96f66bfc7b23a8ef352696d |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" 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.
5 .\" 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.
6 .\" 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]
7 .TH DISKS 1M "Jul 2, 2009"
8 .SH NAME
9 disks \- creates /dev entries for hard disks attached to the system
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fB/usr/sbin/disks\fR [\fB-C\fR] [\fB-r\fR \fIrootdir\fR]
14 .fi
16 .SH DESCRIPTION
17 .sp
18 .LP
19 \fBdevfsadm\fR(1M) is now the preferred command for \fB/dev\fR and should be
20 used instead of \fBdisks\fR.
21 .sp
22 .LP
23 \fBdisks\fR creates symbolic links in the \fB/dev/dsk\fR and \fB/dev/rdsk\fR
24 directories pointing to the actual disk device special files under the
25 \fB/devices\fR directory tree. It performs the following steps:
26 .RS +4
27 .TP
28 1.
29 \fBdisks\fR searches the kernel device tree to see what hard disks are
30 attached to the system. It notes the \fB/devices\fR pathnames for the slices on
31 the drive and determines the physical component of the corresponding
32 \fB/dev/dsk\fR or \fB/dev/rdsk\fR name.
33 .RE
34 .RS +4
35 .TP
36 2.
37 The \fB/dev/dsk\fR and \fB/dev/rdsk\fR directories are checked for disk
38 entries \(mi that is, symbolic links with names of the form
39 \fBc\fR\fIN\fR[\fBt\fR\fIN\fR]\fBd\fR\fIN\fR\fBs\fR\fIN\fR, or
40 \fBc\fR\fIN\fR[\fBt\fR\fIN\fR]\fBd\fRN\fBp\fR\fIN\fR, where \fIN\fR represents
41 a decimal number. \fBc\fR\fIN\fR is the logical controller number, an arbitrary
42 number assigned by this program to designate a particular disk controller. The
43 first controller found on the first occasion this program is run on a system,
44 is assigned number \fB0\fR. \fBt\fR\fIN\fR is the bus-address number of a
45 subsidiary controller attached to a peripheral bus such as \fBSCSI\fR or
46 \fBIPI\fR (the \fBtarget\fR number for \fBSCSI,\fR and the \fBfacility\fR
47 number for \fBIPI\fR controllers). \fBd\fR\fIN\fR is the number of the disk
48 attached to the controller. \fBs\fR\fIN\fR is the \fIslice\fR number on the
49 disk. \fBp\fR\fIN\fR is the FDISK partition number used by \fBfdisk\fR(1M).
50 (x86 Only)
51 .RE
52 .RS +4
53 .TP
54 3.
55 If only some of the disk entries are found in \fB/dev/dsk\fR for a disk that
56 has been found under the \fB/devices\fR directory tree, disks creates the
57 missing symbolic links. If none of the entries for a particular disk are found
58 in \fB/dev/dsk\fR, \fBdisks\fR checks to see if any entries exist for other
59 disks attached to the same controller, and if so, creates new entries using the
60 same controller number as used for other disks on the same controller. If no
61 other \fB/dev/dsk\fR entries are found for slices of disks belonging to the
62 same physical controller as the current disk, \fBdisks\fR assigns the
63 lowest-unused controller number and creates entries for the disk slices using
64 this newly-assigned controller number.
65 .RE
66 .sp
67 .LP
68 \fBdisks\fR is run automatically each time a reconfiguration-boot is performed
69 or when \fBadd_drv\fR(1M) is executed. When invoking \fBdisks\fR manually,
70 first run \fBdrvconfig\fR(1M) to ensure \fB/devices\fR is consistent with the
71 current device configuration.
72 .SS "Notice to Driver Writers"
73 .sp
74 .LP
75 \fBdisks\fR considers all devices with a node type of \fBDDI_NT_BLOCK,\fR
76 \fBDDI_NT_BLOCK_CHAN,\fR \fBDDI_NT_CD,\fR \fBDDI_NT_BLOCK_WWN\fR or
77 \fBDDI_NT_CD_CHAN\fR to be disk devices. \fBdisks\fR requires the minor name of
78 disk devices obey the following format conventions.
79 .sp
80 .LP
81 The minor name for block interfaces consists of a single lowercase ASCII
82 character, \fBa\fR through \fBu\fR, representing the slices and the primary
83 partitions. The minor name for logical drive block interfaces consists of the
84 strings \fBp5\fR through \fBp36\fR. The minor name for character (raw)
85 interfaces consists of a single lowercase ASCII character, \fBa\fR through
86 \fBa\fR, followed by the string \fB,raw\fR, representing the slices and the
87 primary partitions. The minor name for logical drive character (raw) interfaces
88 consists of the string \fBp5\fR through \fBp36\fR followed by \fB,raw\fR.
89 .sp
90 .LP
91 \fBdisks\fR performs the following translations:
92 .RS +4
93 .TP
94 .ie t \(bu
95 .el o
96 \fBa\fR through \fBp\fR to \fBs0\fR through \fBs15\fR
97 .RE
98 .RS +4
99 .TP
100 .ie t \(bu
101 .el o
102 \fBq\fR through \fBu\fR to \fBp0\fR through \fBp4\fR
103 .RE
104 .RS +4
105 .TP
106 .ie t \(bu
107 .el o
108 \fBp5\fR through \fBp36\fR to \fBp5\fR through \fBp36\fR
109 .RE
110 .sp
111 .LP
112 SPARC drivers should only use the first eight slices: \fBa\fR through \fBh\fR,
113 while x86 drivers can use \fBa\fR through \fBu\fR, with \fBq\fR through \fBu\fR
114 corresponding to \fBfdisk\fR(1M) primary partitions. \fBq\fR represents the
115 entire disk, while \fBr\fR, \fBs\fR, \fBt\fR, and \fBu\fR represent up to four
116 additional primary partitions. For logical drives, \fBp5\fR to \fBp36\fR
117 correspond to the 32 logical drives that are supported. The device nodes for
118 logical drives change dynamically as and when they are created or deleted.
119 .sp
120 .LP
121 To prevent \fBdisks\fR from attempting to automatically generate links for a
122 device, drivers must specify a private node type and refrain from using a node
123 type: \fBDDI_NT_BLOCK,\fR \fBDDI_NT_BLOCK_CHAN,\fR \fBDDI_NT_CD,\fR or
124 \fBDDI_NT_CD_CHAN\fR when calling \fBddi_create_minor_node\fR(9F).
125 .SH OPTIONS
126 .sp
127 .LP
128 The following options are supported:
129 .sp
130 .ne 2
131 .na
132 \fB\fB-C\fR\fR
133 .ad
134 .RS 14n
135 Causes disks to remove any invalid links after adding any new entries to
136 \fB/dev/dsk\fR and \fB/dev/rdsk\fR. Invalid links are links which refer to
137 non-existent disk nodes that have been removed, powered off, or are otherwise
138 inaccessible.
139 .RE
141 .sp
142 .ne 2
143 .na
144 \fB\fB-r\fR \fIrootdir\fR\fR
145 .ad
146 .RS 14n
147 Causes \fBdisks\fR to presume that the \fB/dev/dsk\fR, \fB/dev/rdsk\fR and
148 \fB/devices\fR directory trees are found under \fIrootdir\fR, not directly
149 under \fB/\fR.
150 .RE
152 .SH ERRORS
153 .sp
154 .LP
155 If disks finds entries of a particular logical controller linked to different
156 physical controllers, it prints an error message and exits without making any
157 changes to the \fB/dev\fR directory, since it cannot determine which of the two
158 alternative logical-to-physical mappings is correct. The links should be
159 manually corrected or removed before another reconfiguration-boot is performed.
160 .SH EXAMPLES
161 .LP
162 \fBExample 1 \fRCreating Block and Character Minor Devices
163 .sp
164 .LP
165 The following example demonstrates creating the block and character minor
166 devices from within the \fBxkdisk\fR driver's \fBattach\fR(9E) function.
168 .sp
169 .in +2
170 .nf
171 #include <sys/dkio.h>
172 /*
173 * Create the minor number by combining the instance number
174 * with the slice number.
175 */
176 #define MINOR_NUM(i, s) ((i) << 4 | (s))
178 int
179 xkdiskattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
180 {
181 int instance, slice;
182 char name[8];
184 /* other stuff in attach... */
186 instance = ddi_get_instance(dip);
187 for (slice = 0; slice < V_NUMPAR; slice++) {
188 /*
189 * create block device interface
190 */
191 sprintf(name, "%c", slice + 'a');
192 ddi_create_minor_node(dip, name, S_IFBLK,
193 MINOR_NUM(instance, slice), DDI_NT_BLOCK_CHAN, 0);
195 /*
196 * create the raw (character) device interface
197 */
198 sprintf(name,"%c,raw", slice + 'a');
199 ddi_create_minor_node(dip, name, S_IFCHR,
200 MINOR_NUM(instance, slice), DDI_NT_BLOCK_CHAN, 0);
201 }
202 }
203 .fi
204 .in -2
206 .sp
207 .LP
208 Installing the \fBxkdisk\fR disk driver on a Sun Fire 4800, with the driver
209 controlling a \fBSCSI\fR disk (target 3 attached to an \fBisp\fR(7D) \fBSCSI
210 HBA)\fR and performing a reconfiguration-boot (causing disks to be run) creates
211 the following special files in \fB/devices\fR.
213 .sp
214 .in +2
215 .nf
216 # ls -l /devices/ssm@0,0/pci@18,700000/pci@1/SUNW,isptwo@4/
217 brw-r----- 1 root sys 32, 16 Aug 29 00:02 xkdisk@3,0:a
218 crw-r----- 1 root sys 32, 16 Aug 29 00:02 xkdisk@3,0:a,raw
219 brw-r----- 1 root sys 32, 17 Aug 29 00:02 xkdisk@3,0:b
220 crw-r----- 1 root sys 32, 17 Aug 29 00:02 xkdisk@3,0:b,raw
221 brw-r----- 1 root sys 32, 18 Aug 29 00:02 xkdisk@3,0:c
222 crw-r----- 1 root sys 32, 18 Aug 29 00:02 xkdisk@3,0:c,raw
223 brw-r----- 1 root sys 32, 19 Aug 29 00:02 xkdisk@3,0:d
224 crw-r----- 1 root sys 32, 19 Aug 29 00:02 xkdisk@3,0:d,raw
225 brw-r----- 1 root sys 32, 20 Aug 29 00:02 xkdisk@3,0:e
226 crw-r----- 1 root sys 32, 20 Aug 29 00:02 xkdisk@3,0:e,raw
227 brw-r----- 1 root sys 32, 21 Aug 29 00:02 xkdisk@3,0:f
228 crw-r----- 1 root sys 32, 21 Aug 29 00:02 xkdisk@3,0:f,raw
229 brw-r----- 1 root sys 32, 22 Aug 29 00:02 xkdisk@3,0:g
230 crw-r----- 1 root sys 32, 22 Aug 29 00:02 xkdisk@3,0:g,raw
231 brw-r----- 1 root sys 32, 23 Aug 29 00:02 xkdisk@3,0:h
232 crw-r----- 1 root sys 32, 23 Aug 29 00:02 xkdisk@3,0:h,raw
233 .fi
234 .in -2
236 .sp
237 .LP
238 /dev/dsk will contain the disk entries to the block device nodes in
239 \fB/devices\fR
241 .sp
242 .in +2
243 .nf
244 # ls -l /dev/dsk
245 /dev/dsk/c0t3d0s0 -> ../../devices/[...]/xkdisk@3,0:a
246 /dev/dsk/c0t3d0s1 -> ../../devices/[...]/xkdisk@3,0:b
247 /dev/dsk/c0t3d0s2 -> ../../devices/[...]/xkdisk@3,0:c
248 /dev/dsk/c0t3d0s3 -> ../../devices/[...]/xkdisk@3,0:d
249 /dev/dsk/c0t3d0s4 -> ../../devices/[...]/xkdisk@3,0:e
250 /dev/dsk/c0t3d0s5 -> ../../devices/[...]/xkdisk@3,0:f
251 /dev/dsk/c0t3d0s6 -> ../../devices/[...]/xkdisk@3,0:g
252 /dev/dsk/c0t3d0s7 -> ../../devices/[...]/xkdisk@3,0:h
253 .fi
254 .in -2
256 .sp
257 .LP
258 and /dev/rdsk will contain the disk entries for the character device nodes in
259 \fB/devices\fR
261 .sp
262 .in +2
263 .nf
264 # ls -l /dev/rdsk
265 /dev/rdsk/c0t3d0s0 -> ../../devices/[...]/xkdisk@3,0:a,raw
266 /dev/rdsk/c0t3d0s1 -> ../../devices/[...]/xkdisk@3,0:b,raw
267 /dev/rdsk/c0t3d0s2 -> ../../devices/[...]/xkdisk@3,0:c,raw
268 /dev/rdsk/c0t3d0s3 -> ../../devices/[...]/xkdisk@3,0:d,raw
269 /dev/rdsk/c0t3d0s4 -> ../../devices/[...]/xkdisk@3,0:e,raw
270 /dev/rdsk/c0t3d0s5 -> ../../devices/[...]/xkdisk@3,0:f,raw
271 /dev/rdsk/c0t3d0s6 -> ../../devices/[...]/xkdisk@3,0:g,raw
272 /dev/rdsk/c0t3d0s7 -> ../../devices/[...]/xkdisk@3,0:h,raw
273 .fi
274 .in -2
276 .SH FILES
277 .sp
278 .ne 2
279 .na
280 \fB\fB/dev/dsk/*\fR\fR
281 .ad
282 .RS 15n
283 Disk entries (block device interface)
284 .RE
286 .sp
287 .ne 2
288 .na
289 \fB\fB/dev/rdsk/*\fR\fR
290 .ad
291 .RS 15n
292 Disk entries (character device interface)
293 .RE
295 .sp
296 .ne 2
297 .na
298 \fB\fB/devices/*\fR\fR
299 .ad
300 .RS 15n
301 Device special files (minor device nodes)
302 .RE
304 .SH SEE ALSO
305 .sp
306 .LP
307 \fBadd_drv\fR(1M), \fBdevfsadm\fR(1M), \fBfdisk\fR(1M), \fBattributes\fR(5),
308 \fBisp\fR(7D), \fBdevfs\fR(7FS), \fBdkio\fR(7I), \fBattach\fR(9E),
309 \fBddi_create_minor_node\fR(9F)
310 .sp
311 .LP
312 \fI\fR
313 .SH BUGS
314 .sp
315 .LP
316 \fBdisks\fR silently ignores malformed minor device names.