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