Hello Steve, On Sat, Sep 10, 2011 at 11:22 PM, Stephen Cameron <stephenmcameron@xxxxxxxxx> wrote: > 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. The "verbatim license" at http://man7.org/linux/man-pages/licenses.html is the most common, and my preference, but any free license (other than GFDL, because that makes the page unacceptable to Debian) is acceptable. Cheers, Michael > 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/ >> > -- 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
