Sorry for the slow reply, I've been on vacation this past week. What do you suggest? Whatever most of the other man pages use is probably fine, though I will have to check with management at HP to see what the lawyers insist upon, but it would be good if I had something that is commonly used to suggest to them. -- steve On Fri, Sep 9, 2011 at 9:38 AM, Michael Kerrisk <mtk.manpages@xxxxxxxxx> wrote: > Stephen, > > On Fri, Aug 12, 2011 at 4:23 PM, Stephen M. Cameron > <scameron@xxxxxxxxxxxxxxxxxx> wrote: >> From: Stephen M. Cameron <scameron@xxxxxxxxxxxxxxxxxx> >> >> This patch applied to man-pages-3.32. >> >> I obtained the information in this man page as a consequence >> of having worked on the cciss driver for the past several years, >> and having written considerable portions of it. > > Thanks for the page. I've added it for the upcoming 3.33 release. But > what license and copyright do you want to assign to the page? (See > http://man7.org/linux/man-pages/licenses.html) > > Cheers, > > Michael > > >> Signed-off-by: Stephen M. Cameron <scameron@xxxxxxxxxxxxxxxxxx> >> --- >> man4/cciss.4 | 291 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ >> 1 files changed, 291 insertions(+), 0 deletions(-) >> create mode 100644 man4/cciss.4 >> >> diff --git a/man4/cciss.4 b/man4/cciss.4 >> new file mode 100644 >> index 0000000..4f61570 >> --- /dev/null >> +++ b/man4/cciss.4 >> @@ -0,0 +1,291 @@ >> +.\" shorthand for double quote that works everywhere. >> +.ds q \N'34' >> +.TH CCISS 4 "cciss" >> +.SH NAME >> +cciss \- HP Smart Array block driver >> +.SH SYNOPSIS >> +.nf >> +modprobe cciss [ cciss_allow_hpsa=1 ] >> +.fi >> +.SH DESCRIPTION >> +.B cciss >> +is a block driver for older HP Smart Array RAID controllers. >> +.SH OPTIONS >> +.HP >> +cciss_allow_hpsa=1 >> +This option prevents the cciss driver >> +from attempting to drive any controllers which the hpsa driver >> +is capable of controlling, which is to say, the cciss driver >> +is restricted by this option to the following controllers: >> +.nf >> + >> + Smart Array 5300 >> + Smart Array 5i >> + Smart Array 532 >> + Smart Array 5312 >> + Smart Array 641 >> + Smart Array 642 >> + Smart Array 6400 >> + Smart Array 6400 EM >> + Smart Array 6i >> + Smart Array P600 >> + Smart Array P400i >> + Smart Array E200i >> + Smart Array E200 >> + Smart Array E200i >> + Smart Array E200i >> + Smart Array E200i >> + Smart Array E500 >> +.fi >> + >> + >> +.SH SUPPORTED HARDWARE >> +The >> +.B cciss >> +driver supports the following Smart Array boards: >> +.nf >> + >> + Smart Array 5300 >> + Smart Array 5i >> + Smart Array 532 >> + Smart Array 5312 >> + Smart Array 641 >> + Smart Array 642 >> + Smart Array 6400 >> + Smart Array 6400 U320 Expansion Module >> + Smart Array 6i >> + Smart Array P600 >> + Smart Array P800 >> + Smart Array E400 >> + Smart Array P400i >> + Smart Array E200 >> + Smart Array E200i >> + Smart Array E500 >> + Smart Array P700m >> + Smart Array P212 >> + Smart Array P410 >> + Smart Array P410i >> + Smart Array P411 >> + Smart Array P812 >> + Smart Array P712m >> + Smart Array P711m >> +.fi >> +.SH CONFIGURATION DETAILS >> +To configure HP Smart Array controllers, use the HP Array Configuration Utility >> +(either hpacuxe or hpacucli) or the Offline ROM-based Configuration Utility (ORCA) >> +run from the Smart Array's option ROM at boot time. >> +.SH FILES >> +.SS DEVICE NODES >> +The device naming scheme is as follows: >> +.nf >> +Major numbers: >> + 104 cciss0 >> + 105 cciss1 >> + 106 cciss2 >> + 105 cciss3 >> + 108 cciss4 >> + 109 cciss5 >> + 110 cciss6 >> + 111 cciss7 >> + >> +Minor numbers: >> + b7 b6 b5 b4 b3 b2 b1 b0 >> + |----+----| |----+----| >> + | | >> + | +-------- Partition ID (0=wholedev, 1-15 partition) >> + | >> + +-------------------- Logical Volume number >> + >> +The device naming scheme is: >> +/dev/cciss/c0d0 Controller 0, disk 0, whole device >> +/dev/cciss/c0d0p1 Controller 0, disk 0, partition 1 >> +/dev/cciss/c0d0p2 Controller 0, disk 0, partition 2 >> +/dev/cciss/c0d0p3 Controller 0, disk 0, partition 3 >> + >> +/dev/cciss/c1d1 Controller 1, disk 1, whole device >> +/dev/cciss/c1d1p1 Controller 1, disk 1, partition 1 >> +/dev/cciss/c1d1p2 Controller 1, disk 1, partition 2 >> +/dev/cciss/c1d1p3 Controller 1, disk 1, partition 3 >> + >> +.fi >> +.SS FILES IN /proc >> +The files /proc/driver/cciss/cciss[0-9]+ contain information about >> +the configuration of each controller. For example: >> +.nf >> + >> + someone@somehost:/proc/driver/cciss> ls -l >> + total 0 >> + -rw-r--r-- 1 root root 0 2010-09-10 10:38 cciss0 >> + -rw-r--r-- 1 root root 0 2010-09-10 10:38 cciss1 >> + -rw-r--r-- 1 root root 0 2010-09-10 10:38 cciss2 >> + someone@somehost:/proc/driver/cciss> cat cciss2 >> + cciss2: HP Smart Array P800 Controller >> + Board ID: 0x3223103c >> + Firmware Version: 7.14 >> + IRQ: 16 >> + Logical drives: 1 >> + Current Q depth: 0 >> + Current # commands on controller: 0 >> + Max Q depth since init: 1 >> + Max # commands on controller since init: 2 >> + Max SG entries since init: 32 >> + Sequential access devices: 0 >> + >> + cciss/c2d0: 36.38GB RAID 0 >> + someone@somehost:/proc/driver/cciss> >> + >> +.fi >> +.SS FILES IN /sys >> + >> +.HP >> +/sys/bus/pci/devices/<dev>/ccissX/cXdY/model >> + >> +Displays the SCSI INQUIRY page 0 model for logical drive Y of controller X. >> + >> +.HP >> +/sys/bus/pci/devices/<dev>/ccissX/cXdY/rev >> + >> +Displays the SCSI INQUIRY page 0 revision for logical drive Y of controller X. >> + >> +.HP >> +/sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id >> + >> +Displays the SCSI INQUIRY page 83 serial number for logical drive Y of controller X. >> + >> +.HP >> +/sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor >> + >> +Displays the SCSI INQUIRY page 0 vendor for logical drive Y of controller X. >> + >> +.HP >> +/sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY >> + >> +A symbolic link to /sys/block/cciss!cXdY >> + >> +.HP >> +/sys/bus/pci/devices/<dev>/ccissX/rescan >> + >> +Kicks off a rescan of the controller to discover logical drive topology changes. >> + >> +.HP >> +/sys/bus/pci/devices/<dev>/ccissX/resettable >> + >> +A value of 1 indicates the "reset_devices=1" kernel parameter (used by >> +kdump) is honored by this controller. A value of 0 indicates the >> +"reset_devices=1" kernel parameter will not be honored. Some models >> +of Smart Array are not able to honor this parameter. >> + >> +.HP >> +/sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid >> + >> +Displays the 8-byte LUN ID used to address logical drive Y of controller X. >> + >> +.HP >> +/sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level >> + >> +Displays the RAID level of logical drive Y of controller X. >> + >> +.HP >> +/sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count >> + >> +Displays the usage count (number of opens) of logical drive Y of controller X. >> + >> +.SH SCSI tape drive and medium changer support >> + >> +SCSI sequential access devices and medium changer devices are supported and >> +appropriate device nodes are automatically created. (e.g. >> +/dev/st0, /dev/st1, etc. See the "st" man page for more details.) >> +You must enable "SCSI tape drive support for Smart Array 5xxx" and >> +"SCSI support" in your kernel configuration to be able to use SCSI >> +tape drives with your Smart Array 5xxx controller. >> + >> +Additionally, note that the driver will not engage the SCSI core at init >> +time. The driver must be directed to dynamically engage the SCSI core via >> +the /proc filesystem entry which the "block" side of the driver creates as >> +/proc/driver/cciss/cciss* at runtime. This is because at driver init time, >> +the SCSI core may not yet be initialized (because the driver is a block >> +driver) and attempting to register it with the SCSI core in such a case >> +would cause a hang. This is best done via an initialization script >> +(typically in /etc/init.d, but could vary depending on distribution). >> +For example: >> +.nf >> + >> + for x in /proc/driver/cciss/cciss[0-9]* >> + do >> + echo "engage scsi" > $x >> + done >> + >> +.fi >> +Once the SCSI core is engaged by the driver, it cannot be disengaged >> +(except by unloading the driver, if it happens to be linked as a module.) >> + >> +Note also that if no sequential access devices or medium changers are >> +detected, the SCSI core will not be engaged by the action of the above >> +script. >> + >> +.SS Hot plug support for SCSI tape drives >> + >> +Hot plugging of SCSI tape drives is supported, with some caveats. >> +The cciss driver must be informed that changes to the SCSI bus >> +have been made. This may be done via the /proc filesystem. >> +For example: >> + >> + echo "rescan" > /proc/scsi/cciss0/1 >> + >> +This causes the driver to query the adapter about changes to the >> +physical SCSI buses and/or fibre channel arbitrated loop and the >> +driver to make note of any new or removed sequential access devices >> +or medium changers. The driver will output messages indicating what >> +devices have been added or removed and the controller, bus, target and >> +lun used to address the device. It then notifies the SCSI mid layer >> +of these changes. >> + >> +Note that the naming convention of the /proc filesystem entries >> +contains a number in addition to the driver name. (E.g. "cciss0" >> +instead of just "cciss" which you might expect.) >> + >> +Note: ONLY sequential access devices and medium changers are presented >> +as SCSI devices to the SCSI mid layer by the cciss driver. Specifically, >> +physical SCSI disk drives are NOT presented to the SCSI mid layer. The >> +physical SCSI disk drives are controlled directly by the array controller >> +hardware and it is important to prevent the kernel from attempting to directly >> +access these devices too, as if the array controller were merely a SCSI >> +controller in the same way that we are allowing it to access SCSI tape drives. >> + >> +.SS SCSI error handling for tape drives and medium changers >> + >> +The linux SCSI mid layer provides an error handling protocol which >> +kicks into gear whenever a SCSI command fails to complete within a >> +certain amount of time (which can vary depending on the command). >> +The cciss driver participates in this protocol to some extent. The >> +normal protocol is a four step process. First the device is told >> +to abort the command. If that doesn't work, the device is reset. >> +If that doesn't work, the SCSI bus is reset. If that doesn't work >> +the host bus adapter is reset. Because the cciss driver is a block >> +driver as well as a SCSI driver and only the tape drives and medium >> +changers are presented to the SCSI mid layer, and unlike more >> +straightforward SCSI drivers, disk i/o continues through the block >> +side during the SCSI error recovery process, the cciss driver only >> +implements the first two of these actions, aborting the command, and >> +resetting the device. Additionally, most tape drives will not oblige >> +in aborting commands, and sometimes it appears they will not even >> +obey a reset command, though in most circumstances they will. In >> +the case that the command cannot be aborted and the device cannot be >> +reset, the device will be set offline. >> + >> +In the event the error handling code is triggered and a tape drive is >> +successfully reset or the tardy command is successfully aborted, the >> +tape drive may still not allow i/o to continue until some command >> +is issued which positions the tape to a known position. Typically you >> +must rewind the tape (by issuing "mt -f /dev/st0 rewind" for example) >> +before i/o can proceed again to a tape drive which was reset. >> + >> +.SH "SEE ALSO" >> +hpsa(4), hpacucli(8), hpacuxe(8), cciss_vol_status(8), http://cciss.sf.net, >> +and from the linux kernel source, Documentation/blockdev/cciss.txt and >> +Documentation/ABI/testing/sysfs-bus-pci-devices-cciss >> +.SH AUTHORS >> +Don Brace, Steve Cameron, Chase Maupin, Mike Miller, Michael Ni, Charles White, Francis Wiran >> +and probably some other people. >> + >> + >> >> -- >> To unsubscribe from this list: send the line "unsubscribe linux-man" in >> the body of a message to majordomo@xxxxxxxxxxxxxxx >> More majordomo info at http://vger.kernel.org/majordomo-info.html >> > > > > -- > Michael Kerrisk > Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ > Author of "The Linux Programming Interface"; http://man7.org/tlpi/ > -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
