usr/src/man/man1m/tapes.1m

   1 '\" te
   2 .\" Copyright (c) 2002 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 TAPES 1M "Nov 8, 2002"
   7 .SH NAME
   8 tapes \- creates /dev entries for tape drives attached to the system
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB/usr/sbin/tapes\fR [\fB-r\fR \fIroot_dir\fR]
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 \fBdevfsadm\fR(1M) is now the preferred command for \fB/dev\fR and
  19 \fB/devices\fR and should be used instead of \fBtapes\fR.
  20 .sp
  21 .LP
  22 \fBtapes\fR creates symbolic links in the \fB/dev/rmt\fR directory to the
  23 actual tape device special files under the \fB/devices\fR directory tree.
  24 \fBtapes\fR searches the kernel device tree to see what tape devices are
  25 attached to the system. For each equipped tape drive, the following steps are
  26 performed:
  27 .RS +4
  28 .TP
  29 1.
  30 The \fB/dev/rmt\fR directory is searched for a \fB/dev/rmt/\fR\fIn\fR entry
  31 that is a symbolic link to the \fB/devices\fR special node of the current tape
  32 drive. If one is found, this determines the logical controller number of the
  33 tape drive.
  34 .RE
  35 .RS +4
  36 .TP
  37 2.
  38 The rest of the special devices associated with the drive are checked, and
  39 incorrect symbolic links are removed and necessary ones added.
  40 .RE
  41 .RS +4
  42 .TP
  43 3.
  44 If none are found, a new logical controller number is assigned (the
  45 lowest-unused number), and new symbolic links are created for all the special
  46 devices associated with the drive.
  47 .RE
  48 .sp
  49 .LP
  50 \fBtapes\fR does not remove links to non-existent devices; these must be
  51 removed by hand.
  52 .sp
  53 .LP
  54 \fBtapes\fR is run each time a reconfiguration-boot is performed, or when
  55 \fBadd_drv\fR(1M) is executed.
  56 .SS "Notice to Driver Writers"
  57 .sp
  58 .LP
  59 \fBtapes\fR(1M) considers all devices with the node type \fBDDI_NT_TAPE\fR to
  60 be tape devices; these devices must have their minor name created with a
  61 specific format. The minor name encodes operational modes for the tape device
  62 and consists of an \fBASCII\fR string of the form [
  63 \fBl\fR,\fBm\fR,\fBh\fR,\fBc\fR,\fBu\fR ][ \fBb\fR ][ \fBn\fR ].
  64 .sp
  65 .LP
  66 The first character set is used to specify the tape density of the device, and
  67 are named low (\fBl\fR), medium (\fBm\fR), high (\fBh\fR), compressed
  68 (\fBc\fR), and ultra (\fBu\fR). These specifiers only express a relative
  69 density; it is up to the driver to assign specific meanings as needed. For
  70 example, 9 track tape devices interpret these as actual bits-per-inch
  71 densities, where \fBl\fR means 800 \fBBPI,\fR \fBm\fR means 1600 \fBBPI ,\fR
  72 and \fBh\fR means 6250 \fBBPI,\fR whereas 4mm \fBDAT\fR tapes defines \fBl\fR
  73 as standard format, and \fBm\fR, \fB h\fR, \fBc\fR and \fBu\fR as compressed
  74 format. Drivers may choose to implement any or all of these format types.
  75 .sp
  76 .LP
  77 During normal tape operation (non-\fBBSD\fR behavior), once an \fBEOF\fR mark
  78 has been reached, subsequent reads from the tape device return an error. An
  79 explicit IOCTL must be issued to space over the \fBEOF\fR mark before the next
  80 file can be read. \fBb\fR instructs the device to observe \fBBSD\fR behavior,
  81 where reading at \fBEOF\fR will cause the tape device to automatically space
  82 over the \fBEOF\fR mark and begin reading from the next file.
  83 .sp
  84 .LP
  85 \fBn\fR or no-rewind-on-close instructs the driver to not rewind to the
  86 beginning of tape when the device is closed. Normal behavior for tape devices
  87 is to reposition to BOT when closing. See \fBmtio\fR(7I).
  88 .sp
  89 .LP
  90 The minor number for tape devices should be created by encoding the device's
  91 instance number using the tape macro \fBMTMINOR\fR and ORing in the proper
  92 combination of density, \fBBSD\fR behavior, and no-rewind flags. See
  93 \fBmtio\fR(7I).
  94 .sp
  95 .LP
  96 To prevent \fBtapes\fR from attempting to automatically generate links for a
  97 device, drivers must specify a private node type and refrain from using the
  98 node type string \fBDDI_NT_TAPE\fR when calling\fBddi_create_minor_node\fR(9F).
  99 .SH OPTIONS
 100 .sp
 101 .LP
 102 The following options are supported:
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fB-r\fR \fIroot_dir\fR\fR
 107 .ad
 108 .RS 15n
 109 Causes \fBtapes\fR to presume that the \fB/dev/rmt\fR directory tree is found
 110 under \fIroot_dir\fR, not directly under \fB/\fR.
 111 .RE
 112
 113 .SH ERRORS
 114 .sp
 115 .LP
 116 If \fBtapes\fR finds entries of a particular logical controller linked to
 117 different physical controllers, it prints an error message and exits without
 118 making any changes to the \fB/dev\fR directory, since it cannot determine which
 119 of the two alternative logical to physical mappings is correct. The links
 120 should be manually corrected or removed before another reconfiguration boot is
 121 performed.
 122 .SH EXAMPLES
 123 .LP
 124 \fBExample 1 \fRCreating Tape Device Nodes From Within the Driver's
 125 \fBattach()\fR Function
 126 .sp
 127 .LP
 128 This example demonstrates creating tape device nodes from within the
 129 \fBxktape\fR driver's \fBattach\fR(9E) function.
 130
 131 .sp
 132 .in +2
 133 .nf
 134 #include <sys/mtio.h>
 135 struct tape_minor_info {
 136     char *minor_name;
 137     int   minor_mode;
 138 };
 139 /*
 140  * create all combinations of logical tapes
 141 */
 142 static struct tape_minor_info example_tape[] = {
 143    {"",    0},                     /* default tape */
 144    {"l",   MT_DENSITY1},
 145    {"lb",  MT_DENSITY1 | MT_BSD},
 146    {"lbn", MT_DENSITY1 | MT_BSD | MT_NOREWIND},
 147    {"m",   MT_DENSITY2},
 148    {"mb",  MT_DENSITY2 | MT_BSD},
 149    {"mbn", MT_DENSITY2 | MT_BSD | MT_NOREWIND},
 150    {"h",   MT_DENSITY3},
 151    {"hb",  MT_DENSITY3 | MT_BSD},
 152    {"hbn", MT_DENSITY3 | MT_BSD | MT_NOREWIND},
 153    {"c",   MT_DENSITY4},
 154    {"cb",  MT_DENSITY4 | MT_BSD},
 155    {"cbn", MT_DENSITY4| MT_BSD | MT_NOREWIND},
 156    {NULL,  0},
 157 };
 158
 159 int
 160 xktapeattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
 161 {
 162    int instance;
 163    struct tape_minor_info *mdp;
 164       /* other stuff in attach... */
 165    instance = ddi_get_instance(dip);
 166
 167    for (mdp = example_tape; mdp->minor_name != NULL; mdp++) {
 168             ddi_create_minor_node(dip, mdp->minor_name, S_IFCHR,
 169                  (MTMINOR(instance) | mdp->minor_mode), DDI_NT_TAPE, 0);
 170  }
 171 .fi
 172 .in -2
 173
 174 .sp
 175 .LP
 176 Installing the \fBxktape\fR driver on a Sun Fire 4800, with the driver
 177 controlling a \fBSCSI\fR tape (target 4 attached to an \fBisp\fR(7D) \fBSCSI
 178 HBA)\fR and performing a reconfiguration-boot creates the following special
 179 files in \fB/devices\fR.
 180
 181 .sp
 182 .in +2
 183 .nf
 184 # ls -l /devices/ssm@0,0/pci@18,700000/pci@1/SUNW,isptwo@4
 185 crw-rw-rw-   1 root sys   33,136 Aug 29 00:02  xktape@4,0:
 186 crw-rw-rw-   1 root sys   33,200 Aug 29 00:02  xktape@4,0:b
 187 crw-rw-rw-   1 root sys   33,204 Aug 29 00:02  xktape@4,0:bn
 188 crw-rw-rw-   1 root sys   33,152 Aug 29 00:02  xktape@4,0:c
 189 crw-rw-rw-   1 root sys   33,216 Aug 29 00:02  xktape@4,0:cb
 190 crw-rw-rw-   1 root sys   33,220 Aug 29 00:02  xktape@4,0:cbn
 191 crw-rw-rw-   1 root sys   33,156 Aug 29 00:02  xktape@4,0:cn
 192 crw-rw-rw-   1 root sys   33,144 Aug 29 00:02  xktape@4,0:h
 193 crw-rw-rw-   1 root sys   33,208 Aug 29 00:02  xktape@4,0:hb
 194 crw-rw-rw-   1 root sys   33,212 Aug 29 00:02  xktape@4,0:hbn
 195 crw-rw-rw-   1 root sys   33,148 Aug 29 00:02  xktape@4,0:hn
 196 crw-rw-rw-   1 root sys   33,128 Aug 29 00:02  xktape@4,0:l
 197 crw-rw-rw-   1 root sys   33,192 Aug 29 00:02  xktape@4,0:lb
 198 crw-rw-rw-   1 root sys   33,196 Aug 29 00:02  xktape@4,0:lbn
 199 crw-rw-rw-   1 root sys   33,132 Aug 29 00:02  xktape@4,0:ln
 200 crw-rw-rw-   1 root sys   33,136 Aug 29 00:02  xktape@4,0:m
 201 crw-rw-rw-   1 root sys   33,200 Aug 29 00:02  xktape@4,0:mb
 202 crw-rw-rw-   1 root sys   33,204 Aug 29 00:02  xktape@4,0:mbn
 203 crw-rw-rw-   1 root sys   33,140 Aug 29 00:02  xktape@4,0:mn
 204 crw-rw-rw-   1 root sys   33,140 Aug 29 00:02  xktape@4,0:n
 205 .fi
 206 .in -2
 207
 208 .sp
 209 .LP
 210 \fB/dev/rmt\fR will contain the logical tape devices (symbolic links to tape
 211 devices in \fB/devices\fR).
 212
 213 .sp
 214 .in +2
 215 .nf
 216 # ls -l /dev/rmt
 217 /dev/rmt/0    -> ../../devices/[....]/xktape@4,0:
 218 /dev/rmt/0b   -> ../../devices/[....]/xktape@4,0:b
 219 /dev/rmt/0bn  -> ../../devices/[....]/xktape@4,0:bn
 220 /dev/rmt/0c   -> ../../devices/[....]/xktape@4,0:c
 221 /dev/rmt/0cb  -> ../../devices/[....]/xktape@4,0:cb
 222 /dev/rmt/0cbn -> ../../devices/[....]/xktape@4,0:cbn
 223 /dev/rmt/0cn  -> ../../devices/[....]/xktape@4,0:cn
 224 /dev/rmt/0h   -> ../../devices/[....]/xktape@4,0:h
 225 /dev/rmt/0hb  -> ../../devices/[....]/xktape@4,0:hb
 226 /dev/rmt/0hbn -> ../../devices/[....]/xktape@4,0:hbn
 227 /dev/rmt/0hn  -> ../../devices/[....]/xktape@4,0:hn
 228 /dev/rmt/0l   -> ../../devices/[....]/xktape@4,0:l
 229 /dev/rmt/0lb  -> ../../devices/[....]/xktape@4,0:lb
 230 /dev/rmt/0lbn -> ../../devices/[....]/xktape@4,0:lbn
 231 /dev/rmt/0ln  -> ../../devices/[....]/xktape@4,0:ln
 232 /dev/rmt/0m   -> ../../devices/[....]/xktape@4,0:m
 233 /dev/rmt/0mb  -> ../../devices/[....]/xktape@4,0:mb
 234 /dev/rmt/0mbn -> ../../devices/[....]/xktape@4,0:mbn
 235 /dev/rmt/0mn  -> ../../devices/[....]/xktape@4,0:mn
 236 /dev/rmt/0n   -> ../../devices/[....]/xktape@4,0:n
 237 .fi
 238 .in -2
 239
 240 .SH FILES
 241 .sp
 242 .ne 2
 243 .na
 244 \fB\fB/dev/rmt/*\fR\fR
 245 .ad
 246 .RS 14n
 247 logical tape devices
 248 .RE
 249
 250 .sp
 251 .ne 2
 252 .na
 253 \fB\fB/devices/*\fR\fR
 254 .ad
 255 .RS 14n
 256 tape device nodes
 257 .RE
 258
 259 .SH SEE ALSO
 260 .sp
 261 .LP
 262 \fBadd_drv\fR(1M), \fBdevfsadm\fR(1M), \fBattributes\fR(5), \fBisp\fR(7D),
 263 \fBdevfs\fR(7FS), \fBmtio\fR(7I), \fBattach\fR(9E),
 264 \fBddi_create_minor_node\fR(9F)
 265 .sp
 266 .LP
 267 \fI\fR
 268 .SH BUGS
 269 .sp
 270 .LP
 271 \fBtapes\fR silently ignores malformed minor device names.