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