sys/man/3/sd

   1 .TH SD 3
   2 .SH NAME
   3 sd \- storage device interface
   4 .SH SYNOPSIS
   5 .nf
   6 .B bind #S /dev
   7
   8 .B /dev/sdctl
   9 .BI /dev/sd Cu /ctl
  10 .BI /dev/sd Cu /raw
  11 .BI /dev/sd Cu /data
  12 \&...
  13 .fi
  14 .SH DESCRIPTION
  15 The storage device interface serves a two-level directory
  16 giving access to multiple storage units,
  17 typically ATA(PI) or SCSI discs.
  18 Each unit
  19 is accessed via files in the directory named by the controller
  20 to which it is attached,
  21 .IR C  ,
  22 and by its unit number
  23 .IR u .
  24 The controller naming convention for ATA(PI) units starts
  25 with the first controller being named
  26 .LR C ,
  27 the second
  28 .LR D ,
  29 etc. up to a maximum of 4 controllers
  30 .RB ([ C-F ]);
  31 legacy controllers are always 'C' and 'D'.
  32 There can be a maximum of 2 units per ATA(PI) controller
  33 .RB ([ 01 ]).
  34 The controller naming convention for SCSI units starts with
  35 the first controller being named
  36 .LR 0 ,
  37 the second
  38 .LR 1 ,
  39 etc. up to a maximum of 16 controllers
  40 .RB ([ 0-9a-f ]).
  41 There can be a maximum of 16 units per SCSI controller
  42 .RB ([ 0-9a-f ]).
  43 .PP
  44 Units are not accessed before the first attach.
  45 Units may be individually attached using the attach specifier,
  46 for example
  47 .IP
  48 .EX
  49 bind -a '#SsdD0' /dev
  50 .EE
  51 .PP
  52 An attach without a specifier will cause the driver to scan for all possible
  53 units before processing the rest of the name.
  54 .PP
  55 The subdirectory for each unit contains two files,
  56 .I ctl
  57 and
  58 .IR raw .
  59 In addition,
  60 if the unit is a direct-access disc of some type
  61 it may be split into partitions and
  62 the subdirectory may contain a file per partition.
  63 By default,
  64 the partition
  65 .I data
  66 will exist for such media.
  67 .PP
  68 Partitions are added and deleted by writing to the
  69 .I ctl
  70 file
  71 .IP
  72 .EX
  73 part \f2name start-sector end-sector\fP
  74 delpart \f2name\fP
  75 .EE
  76 .PP
  77 The default
  78 .I data
  79 partition may be deleted.
  80 A partition cannot be deleted if a process has it open.
  81 If a change of removable media is detected,
  82 the new media cannot be opened until all open partitions
  83 on the old media are closed.
  84 .PP
  85 Partitions are usually created using
  86 .I fdisk
  87 and
  88 .IR prep (8);
  89 the convention is to name non-Plan 9 partitions after their corresponding operating systems
  90 (e.g.,
  91 .BR /dev/sdC0/dos )
  92 and Plan 9 partitions according to their function
  93 (e.g.,
  94 .BR /dev/sdC0/swap ).
  95 The example in
  96 .IR prep (8)
  97 shows how this is done.
  98 .PP
  99 Reading the
 100 .I ctl
 101 file returns at least one line of textual information about
 102 the unit.
 103 The first line will always be prefixed by
 104 .B inquiry
 105 and will give a manufacturer and model number if possible.
 106 A line prefixed by
 107 .B config
 108 will be returned for appropriate media,
 109 e.g. for ATA(PI) units the remainder of the line contains
 110 configuration information from the device's
 111 .I identify
 112 command (config and capabilities)
 113 and also the available I/O transfer options;
 114 this is a diagnostic aid.
 115 A line prefixed by
 116 .B geometry
 117 will be returned for appropriate media;
 118 at least two numbers will follow,
 119 the first being the number of sectors contained in the unit
 120 and the second the sector size in bytes.
 121 Any remaining information on the
 122 .B geometry
 123 line is unit-dependent,
 124 for instance, head,
 125 cylinder and sector counts for ATA discs.
 126 If any partitions are defined for the media,
 127 their name, start-sector and end-sector will be returned,
 128 prefixed by
 129 .BR part .
 130 .IP
 131 .EX
 132 % cat /dev/sdD0/ctl
 133 inquiry KENWOOD CD-ROM UCR-421  208E10/20/99  7.39  2 M0
 134 config 85C0 capabilities 0F00 dma 00550004 dmactl 00000000
 135 geometry 242725 2352
 136 part data 0 242725
 137 %
 138 .EE
 139 .PP
 140 The use of DMA and multi-sector read/write commands may be
 141 enabled and disabled on ATA(PI) units by writing to the
 142 .B ctl
 143 file
 144 .B dma
 145 and
 146 .B rwm
 147 respectively followed by
 148 .B on
 149 or
 150 .BR off .
 151 For example, to enable DMA on a unit that supports it:
 152 .IP
 153 .EX
 154 % echo 'dma on'>/dev/sd00/ctl
 155 .EE
 156 .PP
 157 If supported by the unit,
 158 the standby timer may be enabled:
 159 .IP
 160 .EX
 161 % echo 'standby \f2T\fP'>/dev/sdC0/ctl
 162 .EE
 163 .PP
 164 where
 165 .I T
 166 is the standby timer period in seconds.
 167 .I T
 168 must be between 30 and 1200,
 169 or can be 0 to disable the timer.
 170 .PP
 171 The
 172 .B raw
 173 file is used to execute an arbitrary command on the unit at
 174 a low level.
 175 This is used by programs such as
 176 .IR scuzz (8)
 177 to manipulate devices that do not fit the simple storage model
 178 or for maintenance purposes.
 179 The following steps may be taken to execute a command
 180 .IP \- 3
 181 Write the command to the
 182 .I raw
 183 file;
 184 .IP \-
 185 Read or write data associated with the command, according to the direction of the transfer.
 186 .IP \-
 187 Read the
 188 .I raw
 189 file to retrieve the status of the command,
 190 returned as a text integer.
 191 .LP
 192 Reading
 193 .B /dev/sdctl
 194 yields information about each controller,
 195 one line per controller.
 196 Writing `\fLconfig \fImessage\fR' to
 197 .B /dev/sdctl
 198 passes
 199 .I message
 200 to the legacy configuration machinery,
 201 used to set attributes such as IRQ, port and size.
 202 Writing `\fIctltype message\fR' to
 203 .B /dev/sdctl
 204 passes
 205 .I message
 206 to
 207 .IR ctltype 's
 208 .B wtopctl
 209 function with a nil
 210 .B sdev
 211 argument,
 212 where
 213 .I ctltype
 214 is a known controller type such as
 215 .B ata
 216 or
 217 .BR scsi .
 218 Writing `\c
 219 .BI sd "ctlletter message\fR'
 220 to
 221 .B /dev/sdctl
 222 passes
 223 .I message
 224 to
 225 .BI sd ctlletter\fR's
 226 .B wtopctl
 227 function with an
 228 .B sdev
 229 argument corresponding to the named controller,
 230 where
 231 .I ctlletter
 232 is a known controller letter such as
 233 .B C
 234 or
 235 .BR 0 .
 236 .SH SOURCE
 237 .B /sys/src/9/port/devsd.c
 238 .br
 239 .B /sys/src/9/*/sd*.[hc]
 240 .SH SEE ALSO
 241 .IR scuzz (8)
 242 .SH BUGS
 243 LUNs (logical unit numbers) are not implemented.
 244 For (S)ATA drives,
 245 LUNs are not merely ignored but are actively
 246 prevented from working except for INQUIRY commands.
 247 .PP
 248 The 4 controller limit for ATA(PI) is not enforced.
 249 .PP
 250 No account is taken of some buggy ATA PCI controllers
 251 such as the CMD640.
 252 .PP
 253 ATA(PI) units come up with DMA and multi-sector read/write
 254 capability disabled.