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
 257 .SS Hot plug support for SCSI tape drives
 258
 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 /proc file system.
 265 For example:
 266
 267     echo "rescan" > /proc/scsi/cciss0/1
 268
 269 This causes the driver to:
 270 .RS
 271 .IP 1. 3
 272 query the adapter about changes to the
 273 physical SCSI buses and/or fibre channel arbitrated loop, and
 274 .IP 2.
 275 make note of any new or removed sequential access devices
 276 or medium changers.
 277 .RE
 278 .LP
 279 The driver will output messages indicating which
 280 devices have been added or removed and the controller, bus, target and
 281 lun used to address each device.
 282 The driver then notifies the SCSI midlayer
 283 of these changes.
 284
 285 Note that the naming convention of the /proc file-system entries
 286 contains a number in addition to the driver name
 287 (e.g., "cciss0"
 288 instead of just "cciss", which you might expect).
 289
 290 Note:
 291 .I Only
 292 sequential access devices and medium changers are presented
 293 as SCSI devices to the SCSI midlayer by the
 294 .B cciss
 295 driver.
 296 Specifically, physical SCSI disk drives are
 297 .I not
 298 presented to the SCSI midlayer.
 299 The only disk devices that are presented to the kernel are logical
 300 drives that the array controller constructs from regions on
 301 the physical drives.
 302 The logical drives are presented to the block layer
 303 (not to the SCSI midlayer).
 304 It is important for the driver to prevent the kernel from accessing the
 305 physical drives directlyi, since these drives are used by the array
 306 controller to construct the logical drives.
 307 .SS SCSI error handling for tape drives and medium changers
 308 The Linux SCSI midlayer provides an error-handling protocol that
 309 is initiated whenever a SCSI command fails to complete within a
 310 certain amount of time (which can vary depending on the command).
 311 The
 312 .B cciss
 313 driver participates in this protocol to some extent.
 314 The normal protocol is a four-step process:
 315 .IP * 3
 316 First, the device is told to abort the command.
 317 .IP *
 318 If that doesn't work, the device is reset.
 319 .IP *
 320 If that doesn't work, the SCSI bus is reset.
 321 .IP *
 322 If that doesn't work the host bus adapter is reset.
 323 .LP
 324 The
 325 .B cciss
 326 driver is a block
 327 driver as well as a SCSI driver and only the tape drives and medium
 328 changers are presented to the SCSI midlayer
 329 Furthermore, unlike more
 330 straightforward SCSI drivers, disk I/O continues through the block
 331 side during the SCSI error-recovery process
 332 Therefore, the
 333 .B cciss
 334 driver implements only the first two of these actions,
 335 aborting the command, and resetting the device.
 336 Note also that most tape drives will not oblige
 337 in aborting commands, and sometimes it appears they will not even
 338 obey a reset command, though in most circumstances they will.
 339 If the command cannot be aborted and the device cannot be
 340 reset, the device will be set offline.
 341
 342 In the event that the error-handling code is triggered and a tape drive is
 343 successfully reset or the tardy command is successfully aborted, the
 344 tape drive may still not allow I/O to continue until some command
 345 is issued that positions the tape to a known position.
 346 Typically you must rewind the tape (by issuing
 347 .I "mt -f /dev/st0 rewind"
 348 for example) before I/O can proceed again to a tape drive that was reset.
 349 .SH "SEE ALSO"
 350 .BR cciss_vol_status (8),
 351 .BR hpsa (4),
 352 .BR hpacucli (8),
 353 .BR hpacuxe (8),
 354
 355 .UR http://cciss.sf.net
 356 .UE ,
 357 and
 358 .I Documentation/blockdev/cciss.txt
 359 and
 360 .I Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
 361 in the Linux kernel source tree
 362 .\" .SH AUTHORS
 363 .\" Don Brace, Steve Cameron, Chase Maupin, Mike Miller, Michael Ni,
 364 .\" Charles White, Francis Wiran
 365 .\" and probably some other people.