man4/cciss.4

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