1.. SPDX-License-Identifier: GPL-2.0
  2
  3=========================================
  4HPSA - Hewlett Packard Smart Array driver
  5=========================================
  6
  7This file describes the hpsa SCSI driver for HP Smart Array controllers.
  8The hpsa driver is intended to supplant the cciss driver for newer
  9Smart Array controllers.  The hpsa driver is a SCSI driver, while the
 10cciss driver is a "block" driver.  Actually cciss is both a block
 11driver (for logical drives) AND a SCSI driver (for tape drives). This
 12"split-brained" design of the cciss driver is a source of excess
 13complexity and eliminating that complexity is one of the reasons
 14for hpsa to exist.
 15
 16Supported devices
 17=================
 18
 19- Smart Array P212
 20- Smart Array P410
 21- Smart Array P410i
 22- Smart Array P411
 23- Smart Array P812
 24- Smart Array P712m
 25- Smart Array P711m
 26- StorageWorks P1210m
 27
 28Additionally, older Smart Arrays may work with the hpsa driver if the kernel
 29boot parameter "hpsa_allow_any=1" is specified, however these are not tested
 30nor supported by HP with this driver.  For older Smart Arrays, the cciss
 31driver should still be used.
 32
 33The "hpsa_simple_mode=1" boot parameter may be used to prevent the driver from
 34putting the controller into "performant" mode.  The difference is that with simple
 35mode, each command completion requires an interrupt, while with "performant mode"
 36(the default, and ordinarily better performing) it is possible to have multiple
 37command completions indicated by a single interrupt.
 38
 39HPSA specific entries in /sys
 40=============================
 41
 42  In addition to the generic SCSI attributes available in /sys, hpsa supports
 43  the following attributes:
 44
 45HPSA specific host attributes
 46=============================
 47
 48  ::
 49
 50    /sys/class/scsi_host/host*/rescan
 51    /sys/class/scsi_host/host*/firmware_revision
 52    /sys/class/scsi_host/host*/resettable
 53    /sys/class/scsi_host/host*/transport_mode
 54
 55  the host "rescan" attribute is a write only attribute.  Writing to this
 56  attribute will cause the driver to scan for new, changed, or removed devices
 57  (e.g. hot-plugged tape drives, or newly configured or deleted logical drives,
 58  etc.) and notify the SCSI midlayer of any changes detected.  Normally this is
 59  triggered automatically by HP's Array Configuration Utility (either the GUI or
 60  command line variety) so for logical drive changes, the user should not
 61  normally have to use this.  It may be useful when hot plugging devices like
 62  tape drives, or entire storage boxes containing pre-configured logical drives.
 63
 64  The "firmware_revision" attribute contains the firmware version of the Smart Array.
 65  For example::
 66
 67	root@host:/sys/class/scsi_host/host4# cat firmware_revision
 68	7.14
 69
 70  The transport_mode indicates whether the controller is in "performant"
 71  or "simple" mode.  This is controlled by the "hpsa_simple_mode" module
 72  parameter.
 73
 74  The "resettable" read-only attribute indicates whether a particular
 75  controller is able to honor the "reset_devices" kernel parameter.  If the
 76  device is resettable, this file will contain a "1", otherwise, a "0".  This
 77  parameter is used by kdump, for example, to reset the controller at driver
 78  load time to eliminate any outstanding commands on the controller and get the
 79  controller into a known state so that the kdump initiated i/o will work right
 80  and not be disrupted in any way by stale commands or other stale state
 81  remaining on the controller from the previous kernel.  This attribute enables
 82  kexec tools to warn the user if they attempt to designate a device which is
 83  unable to honor the reset_devices kernel parameter as a dump device.
 84
 85HPSA specific disk attributes
 86-----------------------------
 87
 88  ::
 89
 90    /sys/class/scsi_disk/c:b:t:l/device/unique_id
 91    /sys/class/scsi_disk/c:b:t:l/device/raid_level
 92    /sys/class/scsi_disk/c:b:t:l/device/lunid
 93
 94  (where c:b:t:l are the controller, bus, target and lun of the device)
 95
 96  For example::
 97
 98	root@host:/sys/class/scsi_disk/4:0:0:0/device# cat unique_id
 99	600508B1001044395355323037570F77
100	root@host:/sys/class/scsi_disk/4:0:0:0/device# cat lunid
101	0x0000004000000000
102	root@host:/sys/class/scsi_disk/4:0:0:0/device# cat raid_level
103	RAID 0
104
105HPSA specific ioctls
106====================
107
108  For compatibility with applications written for the cciss driver, many, but
109  not all of the ioctls supported by the cciss driver are also supported by the
110  hpsa driver.  The data structures used by these are described in
111  include/linux/cciss_ioctl.h
112
113  CCISS_DEREGDISK, CCISS_REGNEWDISK, CCISS_REGNEWD
114	The above three ioctls all do exactly the same thing, which is to cause the driver
115	to rescan for new devices.  This does exactly the same thing as writing to the
116	hpsa specific host "rescan" attribute.
117
118  CCISS_GETPCIINFO
119	Returns PCI domain, bus, device and function and "board ID" (PCI subsystem ID).
120
121  CCISS_GETDRIVVER
122	Returns driver version in three bytes encoded as::
123
124		(major_version << 16) | (minor_version << 8) | (subminor_version)
125
126  CCISS_PASSTHRU, CCISS_BIG_PASSTHRU
127	Allows "BMIC" and "CISS" commands to be passed through to the Smart Array.
128	These are used extensively by the HP Array Configuration Utility, SNMP storage
129	agents, etc.  See cciss_vol_status at http://cciss.sf.net for some examples.