Hello Steve, Any progress with the license? Cheers, Michael On Sun, Sep 11, 2011 at 4:27 PM, Michael Kerrisk <mtk.manpages@xxxxxxxxx> wrote: > 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/ > -- 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
