man4/cciss.4

   1 .\" Copyright (C) 2011, Hewlett-Packard Development Company, L.P.
   2 .\" Written by Stephen M. Cameron <scameron@beardog.cce.hp.com>
   3 .\" Licensed under GNU General Public License version 2 (GPLv2)
   4 .\"
   5 .\" shorthand for double quote that works everywhere.
   6 .ds q \N'34'
   7 .TH CCISS 4 2012-08-05 "Linux" "Linux Programmer's Manual"
   8 .SH NAME
   9 cciss \- HP Smart Array block driver
  10 .SH SYNOPSIS
  11 .nf
  12 modprobe cciss [ cciss_allow_hpsa=1 ]
  13 .fi
  14 .SH DESCRIPTION
  15 .B cciss
  16 is a block driver for older HP Smart Array RAID controllers.
  17 .SS Options
  18 .IR "cciss_allow_hpsa=1" :
  19 This option prevents the
  20 .B cciss
  21 driver from attempting to drive any controllers that the
  22 .BR hpsa (4)
  23 driver is capable of controlling, which is to say, the
  24 .B cciss
  25 driver is restricted by this option to the following controllers:
  26 .nf
  27
  28     Smart Array 5300
  29     Smart Array 5i
  30     Smart Array 532
  31     Smart Array 5312
  32     Smart Array 641
  33     Smart Array 642
  34     Smart Array 6400
  35     Smart Array 6400 EM
  36     Smart Array 6i
  37     Smart Array P600
  38     Smart Array P400i
  39     Smart Array E200i
  40     Smart Array E200
  41     Smart Array E200i
  42     Smart Array E200i
  43     Smart Array E200i
  44     Smart Array E500
  45 .fi
  46 .SS Supported hardware
  47 The
  48 .B cciss
  49 driver supports the following Smart Array boards:
  50 .nf
  51
  52     Smart Array 5300
  53     Smart Array 5i
  54     Smart Array 532
  55     Smart Array 5312
  56     Smart Array 641
  57     Smart Array 642
  58     Smart Array 6400
  59     Smart Array 6400 U320 Expansion Module
  60     Smart Array 6i
  61     Smart Array P600
  62     Smart Array P800
  63     Smart Array E400
  64     Smart Array P400i
  65     Smart Array E200
  66     Smart Array E200i
  67     Smart Array E500
  68     Smart Array P700m
  69     Smart Array P212
  70     Smart Array P410
  71     Smart Array P410i
  72     Smart Array P411
  73     Smart Array P812
  74     Smart Array P712m
  75     Smart Array P711m
  76 .fi
  77 .SS Configuration details
  78 To configure HP Smart Array controllers,
  79 use the HP Array Configuration Utility
  80 (either
  81 .BR hpacuxe (8)
  82 or
  83 .BR hpacucli (8))
  84 or the Offline ROM-based Configuration Utility (ORCA)
  85 run from the Smart Array's option ROM at boot time.
  86 .SH FILES
  87 .SS Device nodes
  88 The device naming scheme is as follows:
  89 .nf
  90
  91 Major numbers:
  92
  93     104     cciss0
  94     105     cciss1
  95     106     cciss2
  96     105     cciss3
  97     108     cciss4
  98     109     cciss5
  99     110     cciss6
 100     111     cciss7
 101
 102 Minor numbers:
 103
 104     b7 b6 b5 b4 b3 b2 b1 b0
 105     |----+----| |----+----|
 106          |           |
 107          |           +-------- Partition ID (0=wholedev, 1-15 partition)
 108          |
 109          +-------------------- Logical Volume number
 110
 111 The device naming scheme is:
 112
 113     /dev/cciss/c0d0         Controller 0, disk 0, whole device
 114     /dev/cciss/c0d0p1       Controller 0, disk 0, partition 1
 115     /dev/cciss/c0d0p2       Controller 0, disk 0, partition 2
 116     /dev/cciss/c0d0p3       Controller 0, disk 0, partition 3
 117
 118     /dev/cciss/c1d1         Controller 1, disk 1, whole device
 119     /dev/cciss/c1d1p1       Controller 1, disk 1, partition 1
 120     /dev/cciss/c1d1p2       Controller 1, disk 1, partition 2
 121     /dev/cciss/c1d1p3       Controller 1, disk 1, partition 3
 122
 123 .fi
 124 .SS Files in /proc
 125 The files
 126 .I /proc/driver/cciss/cciss[0-9]+
 127 contain information about
 128 the configuration of each controller.
 129 For example:
 130 .nf
 131
 132     $ \fBcd /proc/driver/cciss\fP
 133     $ \fBls -l\fP
 134     total 0
 135     -rw-r--r-- 1 root root 0 2010-09-10 10:38 cciss0
 136     -rw-r--r-- 1 root root 0 2010-09-10 10:38 cciss1
 137     -rw-r--r-- 1 root root 0 2010-09-10 10:38 cciss2
 138     $ \fBcat cciss2\fP
 139     cciss2: HP Smart Array P800 Controller
 140     Board ID: 0x3223103c
 141     Firmware Version: 7.14
 142     IRQ: 16
 143     Logical drives: 1
 144     Current Q depth: 0
 145     Current # commands on controller: 0
 146     Max Q depth since init: 1
 147     Max # commands on controller since init: 2
 148     Max SG entries since init: 32
 149     Sequential access devices: 0
 150
 151     cciss/c2d0:   36.38GB       RAID 0
 152
 153 .fi
 154 .SS Files in /sys
 155 .TP
 156 .I /sys/bus/pci/devices/<dev>/ccissX/cXdY/model
 157 Displays the SCSI INQUIRY page 0 model for logical drive
 158 .I Y
 159 of controller
 160 .IR X .
 161 .TP
 162 .I /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
 163 Displays the SCSI INQUIRY page 0 revision for logical drive
 164 .I Y
 165 of controller
 166 .IR X .
 167 .TP
 168 .I /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
 169 Displays the SCSI INQUIRY page 83 serial number for logical drive
 170 .I Y
 171 of controller
 172 .IR X .
 173 .TP
 174 .I /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
 175 Displays the SCSI INQUIRY page 0 vendor for logical drive
 176 .I Y
 177 of controller
 178 .IR X .
 179 .TP
 180 .I /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
 181 A symbolic link to
 182 .IR /sys/block/cciss!cXdY .
 183 .TP
 184 .I /sys/bus/pci/devices/<dev>/ccissX/rescan
 185 When this file is written to, the driver rescans the controller
 186 to discover any new, removed, or modified logical drives.
 187 .TP
 188 .I /sys/bus/pci/devices/<dev>/ccissX/resettable
 189 A value of 1 displayed in this file indicates that
 190 the "reset_devices=1" kernel parameter (used by
 191 .BR kdump )
 192 is honored by this controller.
 193 A value of 0 indicates that the
 194 "reset_devices=1" kernel parameter will not be honored.
 195 Some models of Smart Array are not able to honor this parameter.
 196 .TP
 197 .I /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
 198 Displays the 8-byte LUN ID used to address logical drive
 199 .I Y
 200 of controller
 201 .IR X .
 202 .TP
 203 .I /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
 204 Displays the RAID level of logical drive
 205 .I Y
 206 of controller
 207 .IR X .
 208 .TP
 209 .I /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
 210 Displays the usage count (number of opens) of logical drive
 211 .I Y
 212 of controller
 213 .IR X .
 214 .SS SCSI tape drive and medium changer support
 215 SCSI sequential access devices and medium changer devices are supported and
 216 appropriate device nodes are automatically created (e.g.,
 217 .IR /dev/st0 ,
 218 .IR /dev/st1 ,
 219 etc.; see
 220 .BR st (4)
 221 for more details.)
 222 You must enable "SCSI tape drive support for Smart Array 5xxx" and
 223 "SCSI support" in your kernel configuration to be able to use SCSI
 224 tape drives with your Smart Array 5xxx controller.
 225
 226 Additionally, note that the driver will not engage the SCSI core at
 227 init time.
 228 The driver must be directed to dynamically engage the SCSI core via
 229 the /proc file-system entry,
 230 which the "block" side of the driver creates as
 231 .I /proc/driver/cciss/cciss*
 232 at run time.
 233 This is because at driver init time,
 234 the SCSI core may not yet be initialized (because the driver is a block
 235 driver) and attempting to register it with the SCSI core in such a case
 236 would cause a hang.
 237 This is best done via an initialization script
 238 (typically in
 239 .IR /etc/init.d ,
 240 but could vary depending on distribution).
 241 For example:
 242 .nf
 243
 244     for x in /proc/driver/cciss/cciss[0-9]*
 245     do
 246         echo "engage scsi" > $x
 247     done
 248
 249 .fi
 250 Once the SCSI core is engaged by the driver, it cannot be disengaged
 251 (except by unloading the driver, if it happens to be linked as a module.)
 252
 253 Note also that if no sequential access devices or medium changers are
 254 detected, the SCSI core will not be engaged by the action of the above
 255 script.
 256 .SS Hot plug support for SCSI tape drives
 257 Hot plugging of SCSI tape drives is supported, with some caveats.
 258 The
 259 .B cciss
 260 driver must be informed that changes to the SCSI bus
 261 have been made.
 262 This may be done via the /proc file system.
 263 For example:
 264
 265     echo "rescan" > /proc/scsi/cciss0/1
 266
 267 This causes the driver to:
 268 .RS
 269 .IP 1. 3
 270 query the adapter about changes to the
 271 physical SCSI buses and/or fibre channel arbitrated loop, and
 272 .IP 2.
 273 make note of any new or removed sequential access devices
 274 or medium changers.
 275 .RE
 276 .LP
 277 The driver will output messages indicating which
 278 devices have been added or removed and the controller, bus, target and
 279 lun used to address each device.
 280 The driver then notifies the SCSI midlayer
 281 of these changes.
 282
 283 Note that the naming convention of the /proc file-system entries
 284 contains a number in addition to the driver name
 285 (e.g., "cciss0"
 286 instead of just "cciss", which you might expect).
 287
 288 Note:
 289 .I Only
 290 sequential access devices and medium changers are presented
 291 as SCSI devices to the SCSI midlayer by the
 292 .B cciss
 293 driver.
 294 Specifically, physical SCSI disk drives are
 295 .I not
 296 presented to the SCSI midlayer.
 297 The only disk devices that are presented to the kernel are logical
 298 drives that the array controller constructs from regions on
 299 the physical drives.
 300 The logical drives are presented to the block layer
 301 (not to the SCSI midlayer).
 302 It is important for the driver to prevent the kernel from accessing the
 303 physical drives directly, since these drives are used by the array
 304 controller to construct the logical drives.
 305 .SS SCSI error handling for tape drives and medium changers
 306 The Linux SCSI midlayer provides an error-handling protocol that
 307 is initiated whenever a SCSI command fails to complete within a
 308 certain amount of time (which can vary depending on the command).
 309 The
 310 .B cciss
 311 driver participates in this protocol to some extent.
 312 The normal protocol is a four-step process:
 313 .IP * 3
 314 First, the device is told to abort the command.
 315 .IP *
 316 If that doesn't work, the device is reset.
 317 .IP *
 318 If that doesn't work, the SCSI bus is reset.
 319 .IP *
 320 If that doesn't work the host bus adapter is reset.
 321 .LP
 322 The
 323 .B cciss
 324 driver is a block
 325 driver as well as a SCSI driver and only the tape drives and medium
 326 changers are presented to the SCSI midlayer
 327 Furthermore, unlike more
 328 straightforward SCSI drivers, disk I/O continues through the block
 329 side during the SCSI error-recovery process
 330 Therefore, the
 331 .B cciss
 332 driver implements only the first two of these actions,
 333 aborting the command, and resetting the device.
 334 Note also that most tape drives will not oblige
 335 in aborting commands, and sometimes it appears they will not even
 336 obey a reset command, though in most circumstances they will.
 337 If the command cannot be aborted and the device cannot be
 338 reset, the device will be set offline.
 339
 340 In the event that the error-handling code is triggered and a tape drive is
 341 successfully reset or the tardy command is successfully aborted, the
 342 tape drive may still not allow I/O to continue until some command
 343 is issued that positions the tape to a known position.
 344 Typically you must rewind the tape (by issuing
 345 .I "mt -f /dev/st0 rewind"
 346 for example) before I/O can proceed again to a tape drive that was reset.
 347 .SH SEE ALSO
 348 .BR cciss_vol_status (8),
 349 .BR hpsa (4),
 350 .BR hpacucli (8),
 351 .BR hpacuxe (8),
 352
 353 .UR http://cciss.sf.net
 354 .UE ,
 355 and
 356 .I Documentation/blockdev/cciss.txt
 357 and
 358 .I Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
 359 in the Linux kernel source tree
 360 .\" .SH AUTHORS
 361 .\" Don Brace, Steve Cameron, Chase Maupin, Mike Miller, Michael Ni,
 362 .\" Charles White, Francis Wiran
 363 .\" and probably some other people.