'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.\" 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 disks 1M "2 Jul 2009" "SunOS 5.11" "System Administration Commands"
.SH NAME
disks \- creates /dev entries for hard disks attached to the system
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/disks\fR [\fB-C\fR] [\fB-r\fR \fIrootdir\fR]
.fi

.SH DESCRIPTION
.sp
.LP
\fBdevfsadm\fR(1M) is now the preferred command for \fB/dev\fR and should be
used instead of \fBdisks\fR.
.sp
.LP
\fBdisks\fR creates symbolic links in the \fB/dev/dsk\fR and \fB/dev/rdsk\fR
directories pointing to the actual disk device special files under the
\fB/devices\fR directory tree. It performs the following steps:
.RS +4
.TP
1.
\fBdisks\fR searches the kernel device tree to see what hard disks are
attached to the system. It notes the \fB/devices\fR pathnames for the slices on
the drive and determines the physical component of the corresponding
\fB/dev/dsk\fR or \fB/dev/rdsk\fR name.
.RE
.RS +4
.TP
2.
The \fB/dev/dsk\fR and \fB/dev/rdsk\fR directories are checked for disk
entries \(mi that is, symbolic links with names of the form
\fBc\fR\fIN\fR[\fBt\fR\fIN\fR]\fBd\fR\fIN\fR\fBs\fR\fIN\fR, or
\fBc\fR\fIN\fR[\fBt\fR\fIN\fR]\fBd\fRN\fBp\fR\fIN\fR, where \fIN\fR represents
a decimal number. \fBc\fR\fIN\fR is the logical controller number, an arbitrary
number assigned by this program to designate a particular disk controller. The
first controller found on the first occasion this program is run on a system,
is assigned number \fB0\fR. \fBt\fR\fIN\fR is the bus-address number of a
subsidiary controller attached to a peripheral bus such as \fBSCSI\fR or
\fBIPI\fR (the \fBtarget\fR number for \fBSCSI,\fR and the \fBfacility\fR
number for \fBIPI\fR controllers). \fBd\fR\fIN\fR is the number of the disk
attached to the controller. \fBs\fR\fIN\fR is the \fIslice\fR number on the
disk. \fBp\fR\fIN\fR is the FDISK partition number used by \fBfdisk\fR(1M).
(x86 Only)
.RE
.RS +4
.TP
3.
If only some of the disk entries are found in \fB/dev/dsk\fR for a disk that
has been found under the \fB/devices\fR directory tree, disks creates the
missing symbolic links. If none of the entries for a particular disk are found
in \fB/dev/dsk\fR, \fBdisks\fR checks to see if any entries exist for other
disks attached to the same controller, and if so, creates new entries using the
same controller number as used for other disks on the same controller. If no
other \fB/dev/dsk\fR entries are found for slices of disks belonging to the
same physical controller as the current disk, \fBdisks\fR assigns the
lowest-unused controller number and creates entries for the disk slices using
this newly-assigned controller number.
.RE
.sp
.LP
\fBdisks\fR is run automatically each time a reconfiguration-boot is performed
or when \fBadd_drv\fR(1M) is executed. When invoking \fBdisks\fR manually,
first run \fBdrvconfig\fR(1M) to ensure \fB/devices\fR is consistent with the
current device configuration.
.SS "Notice to Driver Writers"
.sp
.LP
\fBdisks\fR considers all devices with a node type of \fBDDI_NT_BLOCK,\fR
\fBDDI_NT_BLOCK_CHAN,\fR \fBDDI_NT_CD,\fR \fBDDI_NT_BLOCK_WWN\fR or
\fBDDI_NT_CD_CHAN\fR to be disk devices. \fBdisks\fR requires the minor name of
disk devices obey the following format conventions.
.sp
.LP
The minor name for block interfaces consists of a single lowercase ASCII
character, \fBa\fR through \fBu\fR, representing the slices and the primary
partitions. The minor name for logical drive block interfaces consists of the
strings \fBp5\fR through \fBp36\fR. The minor name for character (raw)
interfaces consists of a single lowercase ASCII character, \fBa\fR through
\fBa\fR, followed by the string \fB,raw\fR, representing the slices and the
primary partitions. The minor name for logical drive character (raw) interfaces
consists of the string \fBp5\fR through \fBp36\fR followed by \fB,raw\fR.
.sp
.LP
\fBdisks\fR performs the following translations:
.RS +4
.TP
.ie t \(bu
.el o
\fBa\fR through \fBp\fR to \fBs0\fR through \fBs15\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBq\fR through \fBu\fR to \fBp0\fR through \fBp4\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBp5\fR through \fBp36\fR to \fBp5\fR through \fBp36\fR
.RE
.sp
.LP
SPARC drivers should only use the first eight slices: \fBa\fR through \fBh\fR,
while x86 drivers can use \fBa\fR through \fBu\fR, with \fBq\fR through \fBu\fR
corresponding to \fBfdisk\fR(1M) primary partitions. \fBq\fR represents the
entire disk, while \fBr\fR, \fBs\fR, \fBt\fR, and \fBu\fR represent up to four
additional primary partitions. For logical drives, \fBp5\fR to \fBp36\fR
correspond to the 32 logical drives that are supported. The device nodes for
logical drives change dynamically as and when they are created or deleted.
.sp
.LP
To prevent \fBdisks\fR from attempting to automatically generate links for a
device, drivers must specify a private node type and refrain from using a node
type: \fBDDI_NT_BLOCK,\fR \fBDDI_NT_BLOCK_CHAN,\fR \fBDDI_NT_CD,\fR or
\fBDDI_NT_CD_CHAN\fR when calling \fBddi_create_minor_node\fR(9F).
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-C\fR\fR
.ad
.RS 14n
.rt  
Causes disks to remove any invalid links after adding any new entries to
\fB/dev/dsk\fR and \fB/dev/rdsk\fR. Invalid links are links which refer to
non-existent disk nodes that have been removed, powered off, or are otherwise
inaccessible.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-r\fR \fIrootdir\fR\fR
.ad
.RS 14n
.rt  
Causes \fBdisks\fR to presume that the \fB/dev/dsk\fR, \fB/dev/rdsk\fR and
\fB/devices\fR directory trees are found under \fIrootdir\fR, not directly
under \fB/\fR.
.RE

.SH ERRORS
.sp
.LP
If disks finds entries of a particular logical controller linked to different
physical controllers, it prints an error message and exits without making any
changes to the \fB/dev\fR directory, since it cannot determine which of the two
alternative logical-to-physical mappings is correct. The links should be
manually corrected or removed before another reconfiguration-boot is performed.
.SH EXAMPLES
.LP
\fBExample 1 \fRCreating Block and Character Minor Devices
.sp
.LP
The following example demonstrates creating the block and character minor
devices from within the \fBxkdisk\fR driver's \fBattach\fR(9E) function.

.sp
.in +2
.nf
#include    <sys/dkio.h>
/*
 * Create the minor number by combining the instance number
 * with the slice number.
 */
#define MINOR_NUM(i, s)   ((i) << 4 | (s))

int
xkdiskattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
{
    int instance, slice;
    char name[8];

        /* other stuff in attach... */

    instance = ddi_get_instance(dip);
    for (slice = 0; slice < V_NUMPAR; slice++) {
        /*
         * create block device interface
         */
        sprintf(name, "%c", slice + 'a');
        ddi_create_minor_node(dip, name, S_IFBLK,
            MINOR_NUM(instance, slice), DDI_NT_BLOCK_CHAN, 0);

        /*
         * create the raw (character) device interface
         */
        sprintf(name,"%c,raw", slice + 'a');
        ddi_create_minor_node(dip, name, S_IFCHR,
            MINOR_NUM(instance, slice), DDI_NT_BLOCK_CHAN, 0);
    }
}
.fi
.in -2

.sp
.LP
Installing the \fBxkdisk\fR disk driver on a Sun Fire 4800, with the driver
controlling a \fBSCSI\fR disk (target 3 attached to an \fBisp\fR(7D) \fBSCSI
HBA)\fR and performing a reconfiguration-boot (causing disks to be run) creates
the following special files in \fB/devices\fR.

.sp
.in +2
.nf
# ls -l /devices/ssm@0,0/pci@18,700000/pci@1/SUNW,isptwo@4/
brw-r-----   1 root sys   32, 16 Aug 29 00:02 xkdisk@3,0:a
crw-r-----   1 root sys   32, 16 Aug 29 00:02 xkdisk@3,0:a,raw
brw-r-----   1 root sys   32, 17 Aug 29 00:02 xkdisk@3,0:b
crw-r-----   1 root sys   32, 17 Aug 29 00:02 xkdisk@3,0:b,raw
brw-r-----   1 root sys   32, 18 Aug 29 00:02 xkdisk@3,0:c
crw-r-----   1 root sys   32, 18 Aug 29 00:02 xkdisk@3,0:c,raw
brw-r-----   1 root sys   32, 19 Aug 29 00:02 xkdisk@3,0:d
crw-r-----   1 root sys   32, 19 Aug 29 00:02 xkdisk@3,0:d,raw
brw-r-----   1 root sys   32, 20 Aug 29 00:02 xkdisk@3,0:e
crw-r-----   1 root sys   32, 20 Aug 29 00:02 xkdisk@3,0:e,raw
brw-r-----   1 root sys   32, 21 Aug 29 00:02 xkdisk@3,0:f
crw-r-----   1 root sys   32, 21 Aug 29 00:02 xkdisk@3,0:f,raw
brw-r-----   1 root sys   32, 22 Aug 29 00:02 xkdisk@3,0:g
crw-r-----   1 root sys   32, 22 Aug 29 00:02 xkdisk@3,0:g,raw
brw-r-----   1 root sys   32, 23 Aug 29 00:02 xkdisk@3,0:h
crw-r-----   1 root sys   32, 23 Aug 29 00:02 xkdisk@3,0:h,raw
.fi
.in -2

.sp
.LP
/dev/dsk will contain the disk entries to the block device nodes in
\fB/devices\fR

.sp
.in +2
.nf
# ls -l /dev/dsk
/dev/dsk/c0t3d0s0 -> ../../devices/[...]/xkdisk@3,0:a
/dev/dsk/c0t3d0s1 -> ../../devices/[...]/xkdisk@3,0:b
/dev/dsk/c0t3d0s2 -> ../../devices/[...]/xkdisk@3,0:c
/dev/dsk/c0t3d0s3 -> ../../devices/[...]/xkdisk@3,0:d
/dev/dsk/c0t3d0s4 -> ../../devices/[...]/xkdisk@3,0:e
/dev/dsk/c0t3d0s5 -> ../../devices/[...]/xkdisk@3,0:f
/dev/dsk/c0t3d0s6 -> ../../devices/[...]/xkdisk@3,0:g
/dev/dsk/c0t3d0s7 -> ../../devices/[...]/xkdisk@3,0:h
.fi
.in -2

.sp
.LP
and /dev/rdsk will contain the disk entries for the character device nodes in
\fB/devices\fR

.sp
.in +2
.nf
# ls -l /dev/rdsk
/dev/rdsk/c0t3d0s0 -> ../../devices/[...]/xkdisk@3,0:a,raw
/dev/rdsk/c0t3d0s1 -> ../../devices/[...]/xkdisk@3,0:b,raw
/dev/rdsk/c0t3d0s2 -> ../../devices/[...]/xkdisk@3,0:c,raw
/dev/rdsk/c0t3d0s3 -> ../../devices/[...]/xkdisk@3,0:d,raw
/dev/rdsk/c0t3d0s4 -> ../../devices/[...]/xkdisk@3,0:e,raw
/dev/rdsk/c0t3d0s5 -> ../../devices/[...]/xkdisk@3,0:f,raw
/dev/rdsk/c0t3d0s6 -> ../../devices/[...]/xkdisk@3,0:g,raw
/dev/rdsk/c0t3d0s7 -> ../../devices/[...]/xkdisk@3,0:h,raw
.fi
.in -2

.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/dev/dsk/*\fR\fR
.ad
.RS 15n
.rt  
Disk entries (block device interface)
.RE

.sp
.ne 2
.mk
.na
\fB\fB/dev/rdsk/*\fR\fR
.ad
.RS 15n
.rt  
Disk entries (character device interface)
.RE

.sp
.ne 2
.mk
.na
\fB\fB/devices/*\fR\fR
.ad
.RS 15n
.rt  
Device special files (minor device nodes)
.RE

.SH SEE ALSO
.sp
.LP
\fBadd_drv\fR(1M), \fBdevfsadm\fR(1M), \fBfdisk\fR(1M), \fBattributes\fR(5),
\fBisp\fR(7D), \fBdevfs\fR(7FS), \fBdkio\fR(7I), \fBattach\fR(9E),
\fBddi_create_minor_node\fR(9F)
.sp
.LP
\fI\fR
.SH BUGS
.sp
.LP
\fBdisks\fR silently ignores malformed minor device names.