LDP/LDP/howto/linuxdoc/Antares-RAID-sparcLinux-HOWTO/Antares-RAID-sparcLinux-HOWTO.sgml

<!-- LinuxDoc file was created by LyX 0.12 (C) 1995-1998 by <tcoates> Fri May  5 14:04:33 2000
 -->
<!-- Export filter v0.6 by Pascal Andre/Bernhard Iselborn-->

<!doctype linuxdoc system>

<article>

<title>Antares-RAID-sparcLinux-HOWTO
<author>Thom Coates (tdc3@psu.edu), Carl Munio, Jim Ludemann
<date>v0.1, 28 April 2000
<abstract>This document describes how to install, configure, and maintain a hardware
 RAID built around the 5070 SBUS host based RAID controller by Antares Microsystems.
 Other topics of discussion include RAID levels, the 5070 controller GUI, and
 5070 command line. A complete command reference for the 5070's K9 kernel and
 Bourne-like shell is included.
<toc>
<sect>Preamble
<p>

Copyright 2000 by Thomas D. Coates, Jr. This document's source is licensed
 under the terms if the GNU general public license agreement.
Permission to
 use, copy, modify, and distribute this document without fee for any purpose
 commercial or non-commercial is hereby granted, provided that the author's
 names and this notice appear in all copies and/or supporting documents; and
 that the location where a freely available unmodified version of this document
 may be obtained is given. This document is distributed in the hope that it
 will be useful, but WITHOUT ANY WARRANTY, either expressed or implied. While
 every effort has been taken to ensure the accuracy of the information documented
 herein, the author(s)/editor(s)/maintainer(s)/contributor(s) assumes NO RESPONSIBILITY
 for any errors, or for any damages, direct or consequential, as a result of
 the use of the information documented herein. A complete copy of the GNU Public
 License agreement may be obtained from: 
Free Software Foundation, Inc., 59
 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 Portions of this document
 are adapted and/or re-printed from the 5070 installation guide and man pages
 with permission of Antares Microsystems, Inc., Campbell CA.
<sect>Acknowledgements and Thanks
<p>
<itemize>
<item>Carl and Jim at Antares for the hardware, man pages, and other support/contributions
 they provided during the writing of this document.
<item>Penn State University - Hershey Medical Center, Department of Radiology,
 Section of Clinical Image Management (My home away from my home away from home).
<item>The software-raid-HOWTO Copyright 1997 by Linas Vepstas under the GNU public
 license agreement. The software-raid-HOWTO is Available from : http://www.linuxdoc.org
</itemize>
<sect>New Versions
<p>
<itemize>
<item>The most recent version of this document can be found at my homepage: http://www.xray.hmc.psu.edu/&tilde;tcoates/
<item>Other versions may be found in different formats at the LDP homepage: http://www.linuxdoc.org
 and mirror sites.
</itemize>
<sect>Introduction
<p>

The Antares 5070 is a high performance, versatile, yet relatively inexpensive
 host based RAID controller. Its embedded operating system (K9 kernel) is modelled
 on the Plan 9 operating system whose design is discussed in several papers
 from AT&amp;T (see the &dquot;Further Reading&dquot; section). K9 is a kernel
 targeted at embedded controllers of small to medium complexity (e.g. ISDN-ethernet
 bridges, RAID controllers, etc). It supports multiple lightweight processes
 (i.e. without memory management) on a single CPU with a non-pre-emptive scheduler.
 Device driver architecture is based on Plan 9 (and Unix SVR4) streams. Concurrency
 control mechanisms include semaphores and signals. 


The 5070 has three single ended ultra 1 SCSI channels and two onboard serial
 interfaces one of which provides command line access via a connected serial
 terminal or modem. The other is used to upgrade the firmware. The command line
 is robust, implementing many of the essential Unix commands (e.g. dd, ls, cat,
 etc.) and a scaled down Bourne shell for scripting. The Unix command set is
 augmented with RAID specific configuration commands and scripts. In addition
 to the command line interface an ASCII text based GUI is provided to permit
 easy configuration of level 0, 1, 3, 4, and 5 RAIDs. 
<sect1>5070 Main Features
<p>
<itemize>
<item>RAID levels 0, 1, 3, 4, and 5 are supported.
<item>Text based GUI for easy configuration for all supported RAID levels.
<item>A Multidisk RAID volume appears as an individual SCSI drive to the operating
 system and can be managed with the standard utilities (fdisk, mkfs, fsck,etc.).
 RAID Volumes may be assigned to different SCSI IDs or the same SCSI IDs but
 different LUNs. 
<item>No special RAID drivers required for the host operating system.
<item>Multiple RAID volumes of different levels can be mixed among the drives
 forming the physical plant. For example in a hypothetical drive plant consisting
 of 9 drives: 
<itemize>
<item>2 drives form a level 3 RAID assigned to SCSI ID 5, LUN 0
<item>2 drives form a level 0 RAID assigned to SCSI ID 5, LUN 1
<item>5 drives form a level 5 RAID assigned to SCSI ID 6, LUN 0
</itemize>
<item>Three single ended SCSI channels which can accommodate 6 drives each (18
 drives total).
<item>Two serial interfaces. The first permits configuration/control/monitoring
 of the RAID from a local serial terminal. The second serial port is used to
 upload new programming into the 5070 (using PPP and TFTP). 
<item>Robust Unix-like command line and NVRAM based file system.
<item>Configurable ASCII SCSI communication channel for passing commands to the
 5070's command line interpreter. Allows programming running on host OS to directly
 configure/control/monitor all parameters of the 5070.
</itemize>
<sect>Background
<p>

Much of the information/knowledge pertaining to RAID levels in this section
 is adapted from the software-raid-HOWTO by Linas Vepstas . See the acknowledgements
 section for the URL where the full document may be obtained. 

RAID is an acronym for &dquot;Redundant Array of Inexpensive Disks&dquot;
 and is used to create large, reliable disk storage systems out of individual
 hard disk drives. There are two basic ways of implementing a RAID, software
 or hardware. The main advantage of a software RAID is low cost. However, since
 the OS of the host system must manage the RAID directly there is a substantial
 penalty in performance. Furthermore if the RAID is also the boot device, a
 drive failure could prove disastrous since the operating system and utility
 software needed to perform the recovery is located on the RAID. The primary
 advantages of hardware RAID is performance and improved reliability. Since
 all RAID operations are handled by a dedicated CPU on the controller, the host
 system's CPU is never bothered with RAID related tasks. In fact the host OS
 is completely oblivious to the fact that its SCSI drives are really virtual
 RAID drives. When a drive fails on the 5070 it can be replaced on-the-fly with
 a drive from the spares pool and its data reconstructed without the host's
 OS ever knowing anything has happened.
<sect1>Raid Levels 
<p>

The different RAID levels have different performance, redundancy, storage
 capacity, reliability and cost characteristics. Most, but not all levels of
 RAID offer redundancy against drive failure. There are many different levels
 of RAID which have been defined by various vendors and researchers. The following
 describes the first 7 RAID levels in the context of the Antares 5070 hardware
 RAID implementation.
<sect1>RAID Linear
<p>

RAID-linear is a simple concatenation of drives to create a larger virtual
 drive. It is handy if you have a number small drives, and wish to create a
 single, large drive. This concatenation offers no redundancy, and in fact decreases
 the overall reliability: if any one drive fails, the combined drive will fail.
<sect2>SUMMARY
<p>
<itemize>
<item>Enables construction of a large virtual drive from a number of smaller
 drives
<item>No protection, less reliable than a single drive
<item>RAID 0 is a better choice due to better I/O performance
</itemize>
<sect1>Level 1 
<p>

Also referred to as &dquot;mirroring&dquot;. Two (or more) drives, all
 of the same size, each store an exact copy of all data, disk-block by disk-block.
 Mirroring gives strong protection against drive failure: if one drive fails,
 there is another with the an exact copy of the same data. Mirroring can also
 help improve performance in I/O-laden systems, as read requests can be divided
 up between several drives. Unfortunately, mirroring is also one of the least
 efficient in terms of storage: two mirrored drives can store no more data than
 a single drive.
<sect2>SUMMARY
<p>
<itemize>
<item>Good read/write performance
<item>Inefficient use of storage space (half the total space available for data)
<item>RAID 6 may be a better choice due to better I/O performance. 
</itemize>
<sect1>Striping
<p>

Striping is the underlying concept behind all of the other RAID levels.
 A stripe is a contiguous sequence of disk blocks. A stripe may be as short
 as a single disk block, or may consist of thousands. The RAID drivers split
 up their component drives into stripes; the different RAID levels differ in
 how they organize the stripes, and what data they put in them. The interplay
 between the size of the stripes, the typical size of files in the file system,
 and their location on the drive is what determines the overall performance
 of the RAID subsystem.
<sect1>Level 0 
<p>

Similar to RAID-linear, except that the component drives are divided into
 stripes and then interleaved. Like RAID-linear, the result is a single larger
 virtual drive. Also like RAID-linear, it offers no redundancy, and therefore
 decreases overall reliability: a single drive failure will knock out the whole
 thing. However, the 5070 hardware RAID 0 is the fastest of any of the schemes
 listed here.
<sect2>SUMMARY:
<p>
<itemize>
<item>Use RAID 0 to combine smaller drives into one large virtual drive.
<item>Best Read/Write performance of all the schemes listed here.
<item>No protection from drive failure.
<item>ADVICE: Buy very reliable hard disk drives if you plan to use this scheme.
</itemize>
<sect1>Level 2 and 3
<p>

RAID-2 is seldom used anymore, and to some degree has been made obsolete
 by modern hard disk technology. RAID-2 is similar to RAID-4, but stores ECC
 information instead of parity. Since all modern disk drives incorporate ECC
 under the covers, this offers little additional protection. RAID-2 can offer
 greater data consistency if power is lost during a write; however, battery
 backup and a clean shutdown can offer the same benefits. RAID-3 is similar
 to RAID-4, except that it uses the smallest possible stripe size.
<sect2>SUMMARY
<p>
<itemize>
<item>RAID 2 is largely obsolete
<item>Use RAID 3 to combine separate drives together into one large virtual drive.
<item>Protection against single drive failure,
<item>Good read/write performance.
</itemize>
<sect1>Level 4 
<p>

RAID-4 interleaves stripes like RAID-0, but it requires an additional drive
 to store parity information. The parity is used to offer redundancy: if any
 one of the drives fail, the data on the remaining drives can be used to reconstruct
 the data that was on the failed drive. Given N data disks, and one parity disk,
 the parity stripe is computed by taking one stripe from each of the data disks,
 and XOR'ing them together. Thus, the storage capacity of a an (N+1)-disk RAID-4
 array is N, which is a lot better than mirroring (N+1) drives, and is almost
 as good as a RAID-0 setup for large N. Note that for N=1, where there is one
 data disk, and one parity disk, RAID-4 is a lot like mirroring, in that each
 of the two disks is a copy of each other. However, RAID-4 does NOT offer the
 read-performance of mirroring, and offers considerably degraded write performance.
 In brief, this is because updating the parity requires a read of the old parity,
 before the new parity can be calculated and written out. In an environment
 with lots of writes, the parity disk can become a bottleneck, as each write
 must access the parity disk. 
<sect2>SUMMARY
<p>
<itemize>
<item>Similar to RAID 0
<item>Protection against single drive failure.
<item>Poorer I/O performance than RAID 3
<item>Less of the combined storage space is available for data &lsqb;than RAID
 3&rsqb; since an additional drive is needed for parity information.
</itemize>
<sect1>Level 5
<p>

RAID-5 avoids the write-bottleneck of RAID-4 by alternately storing the
 parity stripe on each of the drives. However, write performance is still not
 as good as for mirroring, as the parity stripe must still be read and XOR'ed
 before it is written. Read performance is also not as good as it is for mirroring,
 as, after all, there is only one copy of the data, not two or more. RAID-5's
 principle advantage over mirroring is that it offers redundancy and protection
 against single-drive failure, while offering far more storage capacity when
 used with three or more drives. 
<sect2>SUMMARY
<p>
<itemize>
<item>Use RAID 5 if you need to make the best use of your available storage space
 while gaining protection against single drive failure.
<item>Slower I/O performance than RAID 3
</itemize>
<sect>Installation
<p>

NOTE: The installation procedure given here for the SBUS controller is
 similar to that found in the manual. It has been modified so minor variations
 in the SPARCLinux installation may be included.
<sect1>SBUS Controller Compatibility
<p>

The 5070 / Linux 2.2 combination was tested on SPARCstation (5, 10, &amp;
 20), Ultra 1, and Ultra 2 Creator. The 5070 was also tested on Linux with Symmetrical
 Multiprocessing (SMP) support on a dual processor Ultra 2 creator 3D with no
 problems. Other 5070 / Linux / hardware combinations may work as well.
<sect1>Hardware Installation Procedure
<p>

If your system is already up and running, you must halt the operating system.
<sect2>GNOME:
<p>
<enum>
<item>From the login screen right click the &dquot;Options&dquot; button.
<item>On the popup menu select System -&gt; Halt.
<item>Click &dquot;Yes&dquot; when the verification box appears
</enum>
<sect2>KDE:
<p>
<enum>
<item>From the login screen right click shutdown.
<item>On the popup menu select shutdown by right clicking its radio button.
<item>Click OK
</enum>
<sect2>XDM:
<p>
<enum>
<item>login as root
<item>Left click on the desktop to bring up the pop-up menu
<item>select &dquot;New Shell&dquot;
<item>When the shell opens type &dquot;halt&dquot; at the prompt and press return
</enum>
<sect2>Console Login (systems without X windows):
<p>
<enum>
<item>Login as root
<item>Type &dquot;halt&dquot;
</enum>
<sect2>All Systems:
<p>

Wait for the message &dquot;power down&dquot; or &dquot;system halted&dquot;
 before proceeding. Turn off your SPARCstation system (Note: Your system may
 have turned itself off following the power down directive), its video monitor,
 external disk expansion boxes, and any other peripherals connected to the system.
 Be sure to check that the green power LED on the front of the system enclosure
 is not lit and that the fans inside the system are not running. Do not disconnect
 the system power cord.

<sect2>SPARCstation 4, 5, 10, 20 &amp; UltraSPARC Systems:
<p>
<enum>
<item>Remove the top cover on the CPU enclosure. On a SPARCstation 10, this is
 done by loosening the captive screw at the top right corner of the back of
 the CPU enclosure, then tilting the top of the enclosure forward while using
 a Phillips screwdriver to press the plastic tab on the top left corner. 
<item>Decide which SBUS slot you will use. Any slot will do. Remove the filler
 panel for that slot by removing the two screws and rectangular washers that
 hold it in.
<item>Remove the SBUS retainer (commonly called the handle) by pressing outward
 on one leg of the retainer while pulling it out of the hole in the printed
 circuit board.
<item>Insert the board into the SBUS slot you have chosen. To insert the board,
 first engage the top of the 5070 RAIDium backpanel into the backpanel of the
 CPU enclosure, then rotate the board into a level position and mate the SBUS
 connectors. Make sure that the SBUS connectors are completely engaged. 
<item>Snap the nylon board retainers inside the SPARCstation over the 5070 RAIDium
 board to secure it inside the system.
<item>Secure the 5070 RAIDium SBUS backpanel to the system by replacing the rectangular
 washers and screws that held the original filler panel in place.
<item>Replace the top cover by first mating the plastic hooks on the front of
 the cover to the chassis, then rotating the cover down over the unit until
 the plastic tab in back snaps into place. Tighten the captive screw on the
 upper right corner. 
</enum>
<sect2>Ultra Enterprise Servers, SPARCserver 1000 &amp;amp; 2000 Systems, SPARCserver
 6XO MP Series:
<p>
<enum>
<item>Remove the two Allen screws that secure the CPU board to the card cage.
 These are located at each end of the CPU board backpanel.
<item>Remove the CPU board from the enclosure and place it on a static-free surface.
<item>Decide which SBUS slot you will use. Any slot will do. Remove the filler
 panel for that slot by removing the two screws and rectangular washers that
 hold it in. Save these screws and washers.
<item>Remove the SBUS retainer (commonly called the handle) by pressing outward
 on one leg of the retainer while pulling it out of the hole in the printed
 circuit board. 
<item>Insert the board into the SBUS slot you have chosen. To insert the board,
 first engage the top of the 5070 RAIDium backpanel into the backpanel of the
 CPU enclosure, then rotate the board into a level position and mate the SBUS
 connectors. Make sure that the SBUS connectors are completely engaged. 
<item>Secure the 5070 RAIDium board to the CPU board with the nylon screws and
 standoffs provided on the CPU board. The standoffs may have to be moved so
 that they match the holes used by the SBUS retainer, as the standoffs are used
 in different holes for an MBus module. Replace the screws and rectangular washers
 that originally held the filler panel in place, securing the 5070 RAIDium SBus
 backpanel to the system enclosure.
<item>Re-insert the CPU board into the CPU enclosure and re-install the Allen-head
 retaining screws that secure the CPU board. 
</enum>
<sect2>All Systems:
<p>
<enum>
<item>Mate the external cable adapter box to the 5070 RAIDium and gently tighten
 the two screws that extend through the cable adapter box. 
<item>Connect the three cables from your SCSI devices to the three 68-pin SCSI-3
 connectors on the Antares 5070 RAIDium. The three SCSI cables must always be
 reconnected in the same order after a RAID set has been established, so you
 should clearly mark the cables and disk enclosures for future disassembly and
 reassembly.
<item>Configure the attached SCSI devices to use SCSI target IDs other than 7,
 as that is taken by the 5070 RAIDium itself. Configuring the target number
 is done differently on various devices. Consult the manufacturer's installation
 instructions to determine the method appropriate for your device. 
<item>As you are likely to be installing multiple SCSI devices, make sure that
 all SCSI buses are properly terminated. This means a terminator is installed
 only at each end of each SCSI bus daisy chain. 
</enum>
<sect2>Verifying the Hardware Installation: 
<p>

These steps are optional but recommended. First, power-on your system and
 interrupt the booting process by pressing the &dquot;Stop&dquot; and &dquot;a&dquot;
 keys (or the &dquot;break&dquot; key if you are on a serial terminal) simultaneously
 as soon as the Solaris release number is shown on the screen. This will force
 the system to run the Forth Monitor in the system EPROM, which will display
 the &dquot;ok&dquot; prompt. This gives you access to many useful low-level
 commands, including: 
<verb>ok show-devs
</verb>
<verb>. . .
</verb>
<verb>/iommu@f,e0000000/sbus@f,e000100SUNW, isp@1,8800000
</verb>
<verb>. . .
</verb>

The first line in the response shown above means that the 5070 RAIDium
 host adapter has been properly recognized. If you don't see a line like this,
 you may have a hardware problem.


Next, to see a listing of all the SCSI devices in your system, you can
 use the probe-scsi-all command, but first you must prepare your system as follows:
<verb>ok setenv auto-boot? False
</verb>
<verb>ok reset
</verb>
<verb>ok probe-scsi-all
</verb>

This will tell you the type, target number, and logical unit number of
 every SCSI device recognized in your system. The 5070 RAIDium board will report
 itself attached to an ISP controller at target 0 with two Logical Unit Numbers
 (LUNs): 0 for the virtual hard disk drive, and 7 for the connection to the
 Graphical User Interface (GUI). Note: the GUI communication channel on LUN
 7 is currently unused under Linux. See the discussion under &dquot;SCSI Monitor
 Daemon (SMON)&dquot; in the &dquot;Advanced Topics&dquot; section for more
 information.


REQUIRED: Perform a reconfiguration boot of the operating system:
<verb>ok boot -r
</verb>

If no image appears on your screen within a minute, you most likely have
 a hardware installation problem. In this case, go back and check each step
 of the installation procedure. This completes the hardware installation procedure.
 
<sect1>Serial Terminal
<p>

If you have a serial terminal at your disposal (e.g. DEC-VT420) it may
 be connected to the controller's serial port using a 9 pin DIN male to DB25
 male serial cable. Otherwise you will need to supplement the above cable with
 a null modem adapter to connect the RAID controller's serial port to the serial
 port on either the host computer or a PC. The terminal emulators I have successfully
 used include Minicom (on Linux), Kermit (on Caldera's Dr. DOS), and Hyperterminal
 (on a windows CE palmtop), however, any decent terminal emulation software
 should work. The basic settings are 9600 baud , no parity, 8 data bits, and
 1 stop bit. 
<sect1>Hard Drive Plant
<p>

Choosing the brand and capacity of the drives that will form the hard drive
 physical plant is up to you. I do have some recommendations:
<itemize>
<item>Remember, you generally get what you pay for. I strongly recommend paying
 the extra money for better (i.e. more reliable) hardware especially if you
 are setting up a RAID for a mission critical project. For example, consider
 purchasing drive cabinets with redundant hot-swappable power supplies, etc.
 
<item>You will also want a UPS for your host system and drive cabinets. Remember,
 RAID levels 3 and 5 protect you from data loss due to drive failure NOT power
 failure.
<item>The drive cabinet you select should have hot swappable drive bays, these
 cost more but are definitely worth it when you need to add/change drives. 
<item>Make sure the cabinet(s) have adequate cooling when fully loaded with drives.
<item>Keep your SCSI cables (internal and external) as short as possible
<item>Mark the drives/cabinet(s) in such a way that you will be able to reconnect
 them to the controller in their original configuration. Once the RAID is configured
 you cannot re-organize you drives without re-configuring the RAID (and subsequently
 erasing the data stored on it).
<item>Keep in mind that although it is physically possible to connect/configure
 up to 6 drives per channel, performance will sharply decrease for RAIDs with
 more than three drives per channel. This is due to the 25 MHz bandwidth limitation
 of the SBUS. Therefore, if read/write performance is an issue go with a small
 number of large drives. If you need a really large RAID (&tilde; 1 terabyte)
 then you will have no other choice but to load the channels to capacity and
 pay the performance penalty. NOTE: if you are serving files over a 10/100 Base
 T network you may not notice the performance decrease since the network is
 usually the bottleneck not the SBUS.
</itemize>
<sect>5070 Onboard Configuration
<p>

Before diving into the RAID configuration I need to define a few terms.
<itemize>
<item>&dquot;RaidRunner&dquot; is the name given to the 5070 controller board.
<item>&dquot;Husky&dquot; is the name given to the shell which produces the &dquot;:raid;&dquot;
 command prompt. It is a command language interpreter that executes commands
 read from the standard input or from a file. Husky is a scaled down model of
 Unix's Bourne shell (sh). One major difference is that husky has no concept
 of current working directory. For more information on the husky shell and command
 prompt see the &dquot;Advanced Topics&dquot; section
<item>The &dquot;host port&dquot; is the SCSI ID assigned to the controller card
 itself. This is usually ID 7.
<item>A &dquot;backend&dquot; is a drive attached to the controller on a given
 channel.
<item>A &dquot;rank&dquot; is a collection of all the backends from each channel
 with the same SCSI ID
(i.e. rank 0 would consist of all the drives with SCSI
 ID 0 on each channel)
<item>Each of the backends is identified by a three digit number where the first
 digit is the channel, the second the SCSI ID of the drive, and the third the
 LUN of the drive. The numbers are separated by a period. The identifier is
 prefixed with a &dquot;D&dquot; if it is a disk or &dquot;T&dquot; if it is
 a tape (e.g. D0.1.0). This scheme is referred to as &lt;device_type_c.s.l&gt;
 in the following documentation.
<item>A &dquot;RAID set&dquot; consists of given number of backends (there are
 certain requirements which I'll come to later)
<item>A &dquot;spare&dquot; is a drive which is unused until there is a failure
 in one of the RAID drives. At that time the damaged drive is automatically
 taken offline and replaced with the spare. The data is then reconstructed on
 the spare and the RAID resumes normal operation. 
<item>Spares may either be &dquot;hot&dquot; or &dquot;warm&dquot; depending
 on user configuration. Hot spares are spun up when the RAID is started, which
 shortens the replacement time when a drive failure occurs. Warm spares are
 spun up when needed, which saves wear on the drive.
</itemize>

The test based GUI can be started by typing &dquot;agui&dquot;
<verb>: raid; agui 
</verb>

at the husky prompt on the serial terminal (or emulator). 

Agui is a simple ASCII based GUI that can be run on the RaidRunner console
 port which enables one to configure the RaidRunner. The only argument agui
 takes is the terminal type that is connected to the RaidRunner console. Current
 supported terminals are dtterm, vt100 and xterm. The default is dtterm.

Each agui screen is split into two areas, data and menu. The data area,
 which generally uses all but the last line of the screen, displays the details
 of the information under consideration. The menu area, which generally is the
 bottom line of the screen, displays a strip menu with a title then list of
 options or sub-menus. Each option has one character enclosed in square brackets
 (e.g. &lsqb;Q&rsqb;uit) which is the character to type to select that option.
 Each menu line allows you to refresh the screen data (in case another process
 on the RaidRunner writes to the console). The refresh character may also be
 used during data entry if the screen is overwritten. The refresh character
 is either &lt;Control-l&gt; or &lt;Control-r&gt;.

When agui starts, it reads the configuration of the RaidRunner and probes
 for every possible backend. As it probes for each backend, it's &dquot;name&dquot;
 is displayed in the bottom left corner of the screen.
<sect1>Main Screen Options 
<p>
<sect2>&lt;Figure 1: Main Screen&gt;

<p>

The Main screen is the first screen displayed. It provides a summary of
 the RaidRunner configuration. At the top is the RaidRunner model, version and
 serial number. Next is a line displaying, for each controller, the SCSI ID's
 for each host port (labeled A, B, C, etc) and total and currently available
 amounts of memory. The next set of lines display the ranks of devices on the
 RaidRunner. Each device follows the nomenclature of &lt;device_type_c.s.l&gt;
 where device_type_ can be D for disk or T for tape, c is the internal channel
 the device is attached to, s is the SCSI ID (Rank) of the device on that channel,
 and l is the SCSI LUN of the device (typically 0).

The next set of lines provide a summary of the Raid Sets configured on
 the RaidRunner. The summary includes the raid set name, it's type, it's size,
 the amount of cache allocated to it and a comma separated list of it's backends.
 See rconf in the &dquot;Advanced Topics&dquot; section for a full description
 of the above.

Next are the spare devices configured. Each spare is named (device_type_c.s.l
 format), followed by it's size (in 512-byte blocks), it's spin state (Hot or
 Warm), it's controller allocation , and finally it's current status (Used/Unused,
 Faulty/Working). If used, the raid set that uses it is nominated.

At the bottom of the data area, the number of controllers, channels, ranks
 and devices are displayed.

The menu line allows one to quit agui or select further actions or sub-menus.
<itemize>
<item>&lsqb;Q&rsqb;uit: Exit the main screen and return to the husky prompt.
<item>&lsqb;R&rsqb;aidSets: Enter the RaidSet configuration screen.
<item>&lsqb;H&rsqb;ostports Enter the Host Port configuration screen.
<item>&lsqb;S&rsqb;pares Enter the Spare Device configuration screen.
<item>&lsqb;M&rsqb;onitor Enter the SCSI Monitor configuration screen.
<item>&lsqb;G&rsqb;eneral Enter the General configuration/information screen.
<item>&lsqb;P&rsqb;robe Re-probe the device backends on the RaidRunner. As each
 backend is probed it's &dquot;name&dquot; (c.s.l format) is displayed in the
 bottom left corner of the screen.
</itemize>

These selections are described in detail below.
<sect1>&lsqb;Q&rsqb;uit 
<p>

Exit the agui main screen and return to the husky ( :raid; ) prompt.
<sect1>&lsqb;R&rsqb;aidSets: 
<p>
<sect2>&lt;Figure 2: RAIDSet Configuration Screen&gt;

<p>

The Raid Set Configuration screen displays a Raid Set in the data area
 and provides a menu which allows you to Add, Delete, Modify, Install (changes)
 and Scroll through all other raid sets (First, Last, Next and Previous). If
 no raid sets have been configured, only the screen title and menu is displayed.
 All attributes of the raid set are displayed. For information on each attribute
 of the raid set, see the rconf command in the &dquot;Advanced Topics&dquot;
 section. The menu line allows one to leave the Raid Set Configuration screen
 or select further actions:
<itemize>
<item>&lsqb;Q&rsqb;uit: Exit the Raid Set Configuration screen and return to
 the Main screen. If you have modified, deleted or added a raid set and have
 not installed the changes you will be asked to confirm this. If you select
 Yes to continue the exit, all changes made since the last install action will
 be discarded.
<item>&lsqb;I&rsqb;nst: This action installs (into the RaidRunner configuration
 area) any changes that may have been made to raid sets, be that deletion, addition
 or modification. If you exit prior to installing, all changes made since the
 last installation will be discarded. The installation process takes time. It
 is complete once the typed &dquot;i&dquot; character, is cleared from the menu
 line.
<item>&lsqb;M&rsqb;od: This action allows you to modify the displayed raid set.
 You will be prompted for each Raid Set attribute that can be changed. The prompt
 includes allowable options or formats required. If you don't wish to change
 a particular attribute, then press the RETURN or TAB key. The attributes you
 can change are the raid set name, I/O mode, status (Active to Inactive), bootmode,
 spares usage, backend zone table usage, IO size (if raid set has never been
 used - i.e. just added), cache size, I/O queues length, host interfaces and
 additional stargd arguments. If you wish to change a single attribute then
 use the RETURN or TAB key to skip all other options. The changed attribute
 will be re-displayed as soon as you press the RETURN key. When specifying cache
 size, you may suffix the number with 'm' or 'M' to indicate the number is in
 Megabytes or with 'k' or 'K' to indicate the number is in Kilobytes. Note you
 can only enter whole integer values. When specifying io size, you may suffix
 the number with 'k' or 'K' to indicate the number is in Kilobytes. When you
 enter data, it is checked for correctness and if incorrect, a message is displayed
 and all changes are discarded and you will have to start again. Remember you
 must install (&lsqb;I&rsqb;nst.) any changes.
<item>&lsqb;A&rsqb;dd: When this option is selected you will be prompted for
 various attributes of the new raid set. These attributes are the raid set name,
 the raid set type, the initial host interface the raid set is to appear on
 (in c.h.l format where c is the controller number, h is the host port (0, 1,
 2 etc) and l is the SCSI LUN) and finally a list of backends. When backends
 are to be entered, the screen displays a list of available backends, each with
 a numeric index (commencing at 0). You select each backend by entering the
 index and once complete enter q for Quit. As each backend index is entered,
 it's backend name is displayed in a comma separated list. When you enter data,
 it is checked for correctness and if incorrect, a message is displayed and
 the addition will be ignored and you will have to start again. Once the backends
 are complete, the newly created raid set will be displayed on the screen with
 supplied and default attributes. You can then modify the raid set to change
 other attributes. Remember you must install (&lsqb;I&rsqb;nst.) any new raid
 sets.
<item>&lsqb;D&rsqb;elete: This action will delete the currently displayed raid
 set. If this raid set is Active, then you will not be allowed to delete it.
 You will have to make it Inactive (via the &lsqb;M&rsqb;od. option) then delete
 it. You will be prompted to confirm the deletion. Once you confirm the deletion,
 the screen will be cleared and the next raid set will be displayed, if configured.
 Remember you must install (&lsqb;I&rsqb;nst.) any changes.
<item>&lsqb;F&rsqb;irst, &lsqb;L&rsqb;ast, &lsqb;N&rsqb;ext and &lsqb;P&rsqb;rev
 allow you to scroll through the configured raid sets.
</itemize>
<sect1>&lsqb;H&rsqb;ostports: 
<p>
<sect2>&lt;Figure 3: Host Port Configuration Screen&gt;

<p>

The Host Port Configuration screen displays for each controller, each host
 port (labelled A, B, C, etc for port number 0, 1, 2, etc) and the assigned
 SCSI ID. If the RaidRunner you use, has external switches for host port SCSI
 ID selection, you may only exit (&lsqb;Q&rsqb;uit) from this screen. If the
 RaidRunner you use, does NOT have external switches for host port SCSI ID selection,
 then you may modify (and hence install) the SCSI ID for any host port. The
 menu line allows one to leave the Host Port Configuration screen or select
 further actions (if NO external host):
<itemize>
<item>&lsqb;Q&rsqb;uit: Exit the Host Port Configuration screen and return to
 the Main screen. If you have modified a host port SCSI ID assignment and have
 not installed the changes you will be asked to confirm this. If you select
 Yes to continue the exit, all changes made since the last install action will
 be discarded.
<item>&lsqb;I&rsqb;nstall: This action installs (into the RaidRunner configuration
 area) any changes that may have been made to host port SCSI ID assign<67> ments.
 If you exit prior to installing, all changes made since the last installation
 will be discarded. The installation process takes time. It is complete once
 the typed &dquot;i&dquot; character, is cleared from the menu line.
<item>&lsqb;M&rsqb;odify: This action allows you to modify the host port SCSI
 ID assignments for each host port on each controller (if NO external host port
 SCSI ID switches). You will be prompted for the SCSI ID for each host port.
 You can enter either a SCSI ID (0 thru 15), the minus &dquot;-&dquot; character
 to clear the SCSI ID assignment or RETURN to SKIP. As you enter data, it is
 checked for correctness and if incorrect, a message will be printed although
 previously correctly entered data will be retained. Remember you must install
 (&lsqb;I&rsqb;nst.) any changes.
</itemize>
<sect1>&lsqb;S&rsqb;pares: 
<p>
<sect2>&lt;Figure 4: Spare Device Configuration Screen&gt;

<p>

The Spare Device Configuration screen displays all configured spare devices
 in the data area and provides a menu which allows you to Add, Delete, Mod<6F>
 ify and Install (changes) spare devices. If no spare devices have been configured,
 only the screen title and menu is displayed. Each spare device displayed, shows
 it's name (in device_type_c.s.l format), it's size in 512-byte blocks, it's
 spin status (Hot or Warm), it's controller allocation, finally it's current
 status (Used/Unused, Faulty/Working). If used, the raid set that uses it is
 nominated. For information on each attribute of a spare device, see the rconf
 command in the &dquot;Advanced Topics&dquot; section. The menu line allows
 one to leave the Spare Device Configuration screen or select further actions:
<itemize>
<item>&lsqb;Q&rsqb;uit: Exit the Spare Device Configuration screen and return
 to the Main screen. If you have modified, deleted or added a spare device and
 have not installed the changes you will be asked to confirm this. If you select
 Yes to continue the exit, all changes made since the last install action will
 be discarded.
<item>&lsqb;I&rsqb;nstall: This action installs (into the RaidRunner configuration
 area) any changes that may have been made to the spare devices, be that deletion,
 addition or modification. If you exit prior to installing, all changes made
 since the last installation will be discarded. The installation process takes
 time. It is complete once the typed &dquot;i&dquot; character, is cleared from
 the menu line.
<item>&lsqb;M&rsqb;odify: This action allows you to modify the unused spare devices.
 You will be prompted for each spare device attribute that can be changed. The
 prompt includes allowable options or formats required. If you don't wish to
 change a particular attribute, then press the RETURN key. The attributes you
 can change are the new size (in 512-byte blocks), the spin state (H or hot
 or W for Warm), and the controller allocation (A for any, 0 for controller
 0, 1 for controller 1, etc). If you wish to change a single attribute of a
 spare device, then use the RETURN key to skip all other attributes for each
 spare device. The changed attribute will not be re-displayed until the last
 prompted attribute is entered (or skipped). When you enter data, it is checked
 for cor<6F> rectness and if incorrect, a message is dis<69> played and all changes
 are discarded and you will have to start again. Remember you must install (&lsqb;I&rsqb;nstall)
 any changes.
<item>&lsqb;A&rsqb;dd: When adding a spare device, the list of available devices
 is displayed and you are required to type in the device name. Once entered,
 the spare is added with defaults which you can change, if required, via the
 &lsqb;M&rsqb;odify option. Remember you must install (&lsqb;I&rsqb;nstall)
 any changes.
<item>&lsqb;D&rsqb;elete: When deleting a spare device, the list of spare devices
 allowed to be deleted is displayed and you are required to type in the required
 device name. Once entered, the spare is deleted from the screen. Remember you
 must install (&lsqb;I&rsqb;nstall) any changes.
</itemize>
<sect1>&lsqb;M&rsqb;onitor: 
<p>
<sect2>&lt;Figure 5: SCSI Monitor Screen&gt;

<p>

The SCSI Monitor Configuration screen displays a table of SCSI monitors
 configured for the RaidRunner. Up to four SCSI monitors may be configured.
 The table columns are entitled Controller, Host Port, SCSI LUN and Protocol
 and each line of the table shows the appropriate SCSI Monitor attribute. For
 details on SCSI Monitor attributes, see the rconf command in the &dquot;Advanced
 Topics&dquot; section. The menu line allows one to leave the SCSI Monitor Configuration
 screen or modify and install the table.
<itemize>
<item>&lsqb;Q&rsqb;uit: Exit the SCSI Monitor Configuration screen and return
 to the Main screen. If you have made changes and have not installed them you
 will be asked to confirm this. If you select Yes to continue the exit, all
 changes made since the last install action will be discarded.
<item>&lsqb;I&rsqb;nstall: This action installs (into the RaidRunner configuration
 area) any changes that may have been made to SCSI Monitor configuration. If
 you exit prior to installing, all changes made since the last installation
 will be discarded. The installation process takes time. It is complete once
 the typed &dquot;i&dquot; character, is cleared from the menu line.
<item>&lsqb;M&rsqb;odify: This action allows you to modify the SCSI Monitor configuration.
 The cursor will be moved around the table, prompting you for input. If you
 do not want to change an attribute, enter RETURN to skip. If you want to delete
 a SCSI monitor then enter the minus &dquot;-&dquot; character when prompted
 for the controller number. If you want to use the default protocol list, then
 enter RETURN at the Protocol List prompt. As you enter data, it is checked
 for correctness and if incorrect, a message will be printed and any previously
 entered data is discarded. You will have to re-enter the data again. Remember
 you must install (&lsqb;I&rsqb;nstall) any changes.
</itemize>
<sect1>&lsqb;G&rsqb;eneral: 
<p>
<sect2>&lt;Figure 6: General Screen&gt;

<p>

The General screen has a blank data area and a menu which allows one to
 Quit and return to the main screen, or to select further sub-menus which provide
 information about Devices, the System Message Logger, Global Environment variables
 and throughput Statistics.
<itemize>
<item>&lsqb;Q&rsqb;uit: Exit the General screen and return to the Main screen.
<item>&lsqb;D&rsqb;evices: Enter the Device information screen. The Devices screen
 displays the name of all devices on the RaidRunner. The menu line allows one
 to Quit and return to the General screen or display information about the devices.

&lt;Figure
 7: Devices Screen&gt;

<itemize>
<item>&lsqb;Q&rsqb;uit: Exit the Devices screen and return to the General screen.
 
<item>&lsqb;I&rsqb;nformation: The Device Information screen displays information
 about each device. You can scroll through the devices. For disks, information
 displayed includes, the device name, serial number, vendor name, product id,
 speed, version, sector size, sector count, total device size in MB, number
 of cylinders, heads and sectors per track and the zone/notch partitions. The
 menu line allows one the leave the Device Information screen or browse through
 devices. 

&lt;Figure 8: Device Information Screen&gt;

<itemize>
<item>&lsqb;Q&rsqb;uit: Exit the Device Information screen and return to the
 Devices screen.
<item>&lsqb;F&rsqb;irst, &lsqb;L&rsqb;ast, &lsqb;N&rsqb;ext and &lsqb;P&rsqb;rev
 allow you to scroll through the devices and hence display their current data
 .
</itemize>
</itemize>
<item>Sys&lsqb;L&rsqb;og: Enter the System Logger Messages screen.

&lt;Figure
 9: System Logger Messages Screen&gt;

<itemize>
<item>&lsqb;Q&rsqb;uit: Exit the System Logger Messages screen and return to
 the General screen.
<item>&lsqb;F&rsqb;irst, &lsqb;L&rsqb;ast, &lsqb;N&rsqb;ext and &lsqb;P&rsqb;rev
 allow you to scroll through the system log.
</itemize>
<item>&lsqb;E&rsqb;nvironment: Enter the Global Environment Variable configuration
 screen. The Environment Variable Configuration screen dis<69> plays all configured
 Global Environment Variables and provides a menu which allows you to Add, Delete,
 Modify and Install (changes) variables. Each variable name is displayed followed
 by an equals &dquot;=&dquot; and the value assigned to that variable enclosed
 in braces - &dquot;&lcub;&dquot; .. &dquot;&rcub;&dquot;. The menu line allows
 you to Quit and return to the General screen or select further actions.

&lt;Figure
 10: Environment Global Variable Configuration Screen&gt;

<itemize>
<item>&lsqb;Q&rsqb;uit: Exit the Environment Variable Configuration screen and
 return to the General screen. If you have modified, deleted or added an environment
 variable and have not installed the changes you will be asked to confirm this.
 If you select Yes to continue the exit, all changes made since the last install
 action will be discarded.
<item>&lsqb;I&rsqb;nst: This action installs (into the RaidRunner configuration
 area) any changes that may have been made to environment variables, be that
 deletion, addition or modification. If you exit prior to installing, all changes
 made since the last installation will be discarded. The installation process
 takes time. It is complete once the typed &dquot;i&dquot; character, is cleared
 from the menu line.
<item>&lsqb;M&rsqb;od: This action allows you to modify an environment variable's
 value. You will be prompted for the name of the environment variable and then
 prompted for it's new value. If the environment variable entered is not found,
 a message will be printed and you will not be prompted for a new value. If
 you do not enter a new value, (i.e. just press RETURN) no change will be made.
 Remember you must install (&lsqb;I&rsqb;nstall) any changes.
<item>&lsqb;A&rsqb;dd: When adding a new environment variable, you will be prompted
 for it's name and value. Providing the variable name is not already used and
 you enter a value, the new variable will be added and displayed. Remember you
 must install (&lsqb;I&rsqb;nstall) any changes.
<item>&lsqb;D&rsqb;elete: When deleting an environment variable, you will be
 prompted for the variable name and if valid, the environment variable will
 be deleted. Remember you must install (&lsqb;I&rsqb;nstall) any changes.
</itemize>
<item>&lsqb;S&rsqb;tats: Enter the Statistics monitoring screen. The Statistics
 screen display various general and specific statistics about raid sets configured
 and running on the RaidRunner. The first section of the data area displays
 the current temperature in degrees Celsius and the current speed of fans in
 the RaidRunner. The next section of the data area displays various statistics
 about the named raid set. The statistics are - the current cache hit rate,
 the cumulative number of reads, read failures, writes and write failures for
 each backend of the raid set and finally the read and write throughput for
 each stargd process (indicated by it's process id) that front's the raid set.
 The menu line allows one the leave the Statistics screen or select further
 actions.

&lt;Figure 11: Statistics Monitoring Screen&gt;

<itemize>
<item>&lsqb;Q&rsqb;uit: Exit the Statistics screen and return to the General
 screen.
<item>&lsqb;F&rsqb;irst, &lsqb;L&rsqb;ast, &lsqb;N&rsqb;ext and &lsqb;P&rsqb;rev
 allow you to scroll through the statistics. 
<item>&lsqb;R&rsqb;efresh: This option will get the statistics for the given
 raid set and re-display the current statistics on the screen. 
<item>&lsqb;Z&rsqb;ero: This option will zero the cumulative statistics for the
 currently displayed raid set. 
<item>&lsqb;C&rsqb;ontinuous: This option will start a back<63> ground process that
 will update the statis<69> tics of the currently displayed raid set every 2 seconds.
 A loop counter is created and updated every 2 seconds also. To inter<65> rupt
 this continuous mode of gathering statistics, just press any character. If
 you need to re-fresh the display, then press the refresh characters - &lt;Control-l&gt;
 or &lt;Con<6F> trol-r&gt;.
</itemize>
</itemize>
<sect1>&lsqb;P&rsqb;robe
<p>

The probe option re-scans the SCSI channels and updates the backend list
 with the hardware it finds.
<sect1>Example RAID Configuration Session
<p>

The generalized procedure for configuration consists of three steps arranged
 in the following order:
<enum>
<item>Configuring the Host Port(s) 
<item>Assigning Spares
<item>Configuring the RAID set
</enum>

Note that there is a minimum number of backends required for the various
 supported RAID levels:
<itemize>
<item>Level 0 : 2 backends
<item>Level 3 : 2 backends
<item>Level 5 : 3 backends
</itemize>

In this example we will configure a RAID 5 using 6, 2.04 gigabyte drives.
 The total capacity of the virtual drive will be 10 gigabytes (the equivalent
 of one drive is used for redundancy). This same configuration procedure can
 be used to configure other levels of RAID sets by changing the type parameter.
<enum>
<item>Power on the computer with the serial terminal connected to the RaidRunner's
 serial port. 
<item>When the husky ( :raid; ) prompt appears, Start the GUI by typing &dquot;agui&dquot;
 and pressing return.
<item>When the main screen appears, select &dquot;H&dquot; for &lsqb;H&rsqb;ostport
 configuration
<item>On some models of RaidRunner the host port in not configurable. If you
 have only a &lsqb;Q&rsqb;uit option here then there is nothing further to be
 done for the host port configuration, note the values and skip to step 6. If
 you have add/modify options then your host port is software configurable. 
<item>If there is no entry for a host port on this screen, add an entry with
 the parameters: controller=0, hostport=0 , SCSI ID=0. Don't forget to &lsqb;I&rsqb;nstall
 your changes. If there is already and entry present, note the values (they
 will be used in a later step).
<item>From this point onward I will assume the following hardware configuration:
 
<enum>
<item>There are 7 - 2.04 gig drives connected as follows: 
<enum>
<item>2 drives on SCSI channel 0 with SCSI IDs 0 and 1 (backends 0.0.0, and 0.1.0,
 respectively).
<item>3 drives on SCSI channel 1 with SCSI IDs 0 ,1 and 5 (backends 1.0.0, 1.1.0,
 and 1.5.0).
<item>2 drives on SCSI channel 2 with SCSI IDs 0 and 1 (backends 2.0.0 and 2.1.0).
</enum>
<item>Therefore:
<enum>
<item>Rank 0 consists of backends 0.0.0, 1.0.0, 2.0.0
<item>Rank 1 consists of backends 0.1.0, 1.1.0, 2.1.0
<item>Rank 5 contains only the backend 1.5.0
</enum>
<item>The RaidRunner is assigned to controller 0, hostport 0
</enum>
<item>Press Q to &lsqb;Q&rsqb;uit the hostports screen and return to the Main
 screen. 
<item>Press S to enter the &lsqb;S&rsqb;pares screen
<item>Select A to &lsqb;A&rsqb;dd a new spare to the spares pool. A list of available
 backends will be displayed and you will be prompted for the following information:
 <tscreen>
<verb>Enter the device name to add to spares - from above: 
</verb></tscreen>
</enum>

enter 
<verb>D1.5.0
</verb>

<enum>
<enum>
<enum>
<item>Select I to &lsqb;I&rsqb;nstall your changes
<item>Select Q to &lsqb;Q&rsqb;uit the spares screen and return to the Main screen
<item>Select R from the Main screen to enter the &lsqb;R&rsqb;aidsets screen.
<item>Select A to &lsqb;A&rsqb;dd a new RAID set. You will be prompted for each
 of the RAID set parameters. The prompts and responses are given below.
</enum>
<item>Enter the name of Raid Set: cim_homes (or whatever you want to call it).
<item>Raid set type &lsqb;0,1,3,5&rsqb;: 5 
<item>Enter initial host interface - ctlr,hostport,scsilun: 0.0.0 

Now a list
 of the available backends will be displayed in the form: 
0 - D0.0.0 1 - D1.0.0
 2 - D2.0.0 3 - D0.1.0 4 - D1.1.0 5 - D2.1.0
<item>Enter index from above - Q to Quit:
1 press return
2 press return
3 press
 return
4 press return
5 press return
Q
</enum>
<item>After pressing Q you will be returned to the Raid Sets screen. You should
 see the newly configured Raid set displayed in the data area.
<item>Press I to &lsqb;I&rsqb;nstall the changes

&lt;Figure 12: The RaidSets
 screen of the GUI showing the newly configured RAID 5&gt;

<item>Press Q to exit the RaidSet screen and return to the Main screen
<item>Press Q to &lsqb;Q&rsqb;uit agui and exit to the husky prompt.
<item>type &dquot;reboot&dquot; then press enter. This will reboot the RaidRunner
 (not the host machine.)
<item>When the RaidRunner reboots it will prepare the drives for the newly configured
 RAID. 
NOTE: Depending on the size of the RAID this could take a few minutes
 to a few hours. For the above example it takes the 5070 approximately 10 -
 20 minutes to stripe the RAID set.
<item>Once you see the husky prompt again the RAID is ready for use. You can
 then proceed with the Linux configuration.
</enum>

<sect>Linux Configuration
<p>

These instructions cover setting up the virtual RAID drives on RedHat Linux
 6.1. Setting it up under other Linux distributions should not be a problem.
 The same general instructions apply. 

If you are new to Linux you may want to consider installing Linux from
 scratch since the RedHat installer will do most of the configuration work for
 you. If so skip to section titled &dquot;New Linux Installation.&dquot; Otherwise
 go to the &dquot;Existing Linux Installation&dquot; section (next).
<sect1>Existing Linux Installation
<p>

Follow these instructions if you already have Redhat Linux installed on
 your system and you do not want to re-install. If you are installing the RAID
 as part of a new RedHat Linux installation (or are re-installing) skip to the
 &dquot;New Linux Installation&dquot; section.
<sect2>QLogic SCSI Driver
<p>

The driver can either be loaded as a module or compiled into your kernel.
 If you want to boot from the RAID then you may want to use a kernel with compiled
 in QLogic support (see the kernel-HOWTO available from http://www.linuxdoc.org.
 To use the modular driver become the superuser and add the following lines
 to /etc/conf.modules:
<verb>alias qlogicpti /lib/modules/preferred/scsi/qlogicpti 
</verb>

Change the above path to where ever your SCSI modules live. Then add the
 following line to you /etc/fstab (with the appropriate changes for device and
 mount point, see the fstab man page if you are unsure)
<verb>/dev/sdc1 /home ext2 defaults 1 2
</verb>

Or, if you prefer to use a SYSV initialization script, create a file called
 "raid" in the /etc/rc.d/init.d directory with the following contents (NOTE:
 while there are a few good reasons to start the RAID using a script, one of
 the aforementioned methods would be preferable):
<verb>&num;!/bin/bash

case &dquot;&dollar;1&dquot; in

      start)
      echo &dquot;Loading raid module&dquot;
      /sbin/modprobe qlogicpti
      echo
      echo &dquot;Checking and Mounting raid volumes...&dquot;
      mount -t ext2 -o check /dev/sdc1 /home
      touch /var/lock/subsys/raid
      ;;

      stop)
      echo &dquot;Unmounting raid volumes&dquot;
      umount /home
      echo &dquot;Removing raid module(s)&dquot;
      /sbin/rmmod qlogicpti
      rm -f /var/lock/subsys/raid
      echo
      ;;

      restart)

          &dollar;0 stop 
          &dollar;0 start 
      ;; 

      *)

      echo &dquot;Usage: raid &lcub;start|stop|restart&rcub;&dquot;

      exit 1

esac

exit 0 
</verb>

You will need to edit this example and substitute your device name(s) in
 place of /dev/sdc1 and mount point(s) in place of /home. The next step is to
 make the script executable by root by doing: 
<verb>chmod 0700 /etc/rc.d/init.d/raid
</verb>

Now use your run level editor of choice (tksysv, ksysv, etc.) to add the
 script to the appropriate run level.
<sect2>Device mappings
<p>

Linux uses dynamic device mappings you can determine if the drives were
 found by typing:
<verb>more /proc/scsi/scsi
</verb>

one or more of the entries should look something like this:
<verb>Host: scsi1 Channel: 00 Id: 00 Lun: 00 
</verb>
<verb>Vendor: ANTARES Model: CX106 Rev: 0109
</verb>
<verb>Type: Direct-Access ANSI SCSI revision: 02
</verb>

There may also be one which looks like this:
<verb>Host: scsi1 Channel: 00 Id: 00 Lun: 07
</verb>
<verb>Vendor: ANTARES Model: CX106-SMON Rev: 0109
</verb>
<verb>Type: Direct-Access ANSI SCSI revision: 02
</verb>

This is the SCSI monitor communications channel which is currently un-used
 under Linux (see SMON in the advanced topics section below). 

To locate the drives (following reboot) type:
<verb>dmesg | more
</verb>

Locate the section of the boot messages pertaining to you SCSI devices.
 You should see something like this:
<verb>qpti0: IRQ 53 SCSI ID 7 (Firmware v1.31.32)(Firmware 1.25 96/10/15) 
</verb>
<verb>&lsqb;Ultra Wide, using single ended interface&rsqb;
</verb>
<verb>QPTI: Total of 1 PTI Qlogic/ISP hosts found, 1 actually in use.
</verb>
<verb>scsi1 : PTI Qlogic,ISP SBUS SCSI irq 53 regs at fd018000 PROM node ffd746e0
 
</verb>

Which indicates that the SCSI controller was properly recognized, Below
 this look for the disk section:
<verb>Vendor ANTARES Model: CX106 Rev: 0109
</verb>
<verb>Type: Direct-Access ANSI SCSI revision: 02
</verb>
<verb>Detected scsi disk sdc at scsi1, channel 0, id 0, lun 0
</verb>
<verb>SCSI device sdc: hdwr sector= 512 bytes. Sectors= 20971200 &lsqb;10239
 MB&rsqb; &lsqb;10.2 GB&rsqb;
</verb>

Note the line that reads &dquot;Detected scsi disk sdc ...&dquot; this
 tells you that this virtual disk has been mapped to device /dev/sdc. Following
 partitioning the first partition will be /dev/sdc1, the second will be /dev/sdc2,
 etc. There should be one of the above disk sections for each virtual disk that
 was detected. There may also be an entry like the following:
<verb>Vendor ANTARES Model: CX106-SMON Rev: 0109
</verb>
<verb>Type: Direct-Access ANSI SCSI revision: 02
</verb>
<verb>Detected scsi disk sdd at scsi1, channel 0, id 0, lun 7
</verb>
<verb>SCSI device sdd: hdwr sector= 512 bytes. Sectors= 20971200 &lsqb;128 MB&rsqb;
 &lsqb;128.2 MB&rsqb;
</verb>

BEWARE: this is not a drive DO NOT try to fdisk, mkfs, or mount it!! Doing
 so WILL hang your system.
<sect2>Partitioning
<p>

A virtual drive appears to the host operating system as a large but otherwise
 ordinary SCSI drive. Partitioning is performed using fdisk or your favorite
 utility. You will have to give the virtual drive a disk label when fdisk is
 started. Using the choice "Custom with autoprobed defaults" seems to work
 well. See the man page for the given utility for details. 
<sect2>Installing a filesystem 
<p>

Installing a filesystem is no different from any other SCSI drive:
<verb>mkfs -t &lt;filesystem_type&gt; /dev/&lt;device&gt;
</verb>

for example:
<verb>mkfs -t ext2 /dev/sdc1
</verb>
<sect2>Mounting
<p>

If QLogic SCSI support is compiled into you kernel OR you are loading the
 &dquot;qlogicpti&dquot; module at boot from /etc/conf.modules then add the
 following line(s) to the /etc/fstab:
<verb>/dev/&lt;device&gt; &lt;mount point&gt; ext2 defaults 1 1
</verb>

If you are using a SystemV initialization script to load/unload the module
 you must mount/unmount the drives there as well. See the example script above.
<sect1>New Linux Installation
<p>

This is the easiest way to install the RAID since the RedHat installer
 program will do most of the work for you.
<enum>
<item>Configure the host port, RAID sets, and spares as outlined in &dquot;Onboard
 Configuration.&dquot; Your computer must be on to perform this step since the
 5070 is powered from the SBUS. It does not matter if the computer has an operating
 system installed at this point all we need is power to the controller card.
<item>Begin the RedHat SparcLinux installation
<item>The installation program will auto detect the 5070 controller and load
 the Qlogic driver
<item>Your virtual RAID drives will appear as ordinary SCSI hard drives to be
 partitioned and formatted during the installation. NOTE: When using the graphical
 partitioning utility during the RedHat installation DO NOT designate any partition
 on the virtual drives as type RAID since they are already hardware managed
 virtual RAID drives. The RAID selection on the partitioning utilities screen
 is for setting up a software RAID.
IMPORTANT NOTE: you may see a small SCSI
 drive ( usually &tilde;128 MB) on the list of available drives. DO NOT select
 this drive for use. It is the SMON communication channel NOT a drive. If setup
 tries to use it the installer will hang.
<item>Thats it, the installation program takes care of everything else !!
</enum>
<sect>Maintenance
<p>
<sect1>Activating a spare
<p>

When running a RAID 3 or 5 (if you configured one or more drives to be
 spares) the 5070 will detect when a drive goes offline and automatically select
 a spare from the spares pool to replace it. The data will be rebuilt on-the-fly.
 The RAID will continue operating normally during the re-construction process
 (i.e. it can be read from and written to just is if nothing has happened).
 When a backend fails you will see messages similar to the following displayed
 on the 5070 console:
<verb>930 secs: Redo:1:1 Retry:1 (DIO_cim_homes_D1.1.0_q1) CDB=28(Read_10)Re-/Selection
 Time-out @682400+16
</verb>
<verb>932 secs: Redo:1:1 Retry:2 (DIO_cim_homes_D1.1.0_q1) CDB=28(Read_10)Re-/Selection
 Time-out @682400+16
</verb>
<verb>933 secs: Redo:1:1 Retry:3 (DIO_cim_homes_D1.1.0_q1) CDB=28(Read_10)Re-/Selection
 Time-out @682400+16
</verb>
<verb>934 secs: CIO_cim_homes_q3 R5_W(3412000, 16): Pre-Read drive 4 (D1.1.0)
 fails with result &dquot;Re-/Selection Time-out&dquot;
</verb>
<verb>934 secs: CIO_cim_homes_q2 R5: Drained alternate jobs for drive 4 (D1.1.0)
</verb>
<verb>934 secs: CIO_cim_homes_q2 R5: Drained alternate jobs for drive 4 (D1.1.0)
 RPT 1/0
</verb>
<verb>934 secs: CIO_cim_homes_q2 R5_W(524288, 16): Initial Pre-Read drive 4 (D1.1.0)
 fails with result &dquot;Re-/Selection Time-out&dquot;
</verb>
<verb>935 secs: Redo:1:0 Retry:1 (DIO_cim_homes_D1.0.0_q1) CDB=28(Read_10)SCSI
 Bus &tilde;Reset detected @210544+16
</verb>
<verb>936 secs: Failed:1:1 Retry:0 (rconf) CDB=2A(Write_10)Re-/Selection Time-out
 @4194866+128
</verb>

Then you will see the spare being pulled from the spares pool, spun up,
 tested, engaged, and the data reconstructed.
<verb>937 secs: autorepair pid=1149 /raid/cim_homes: Spinning up spare device
</verb>
<verb>938 secs: autorepair pid=1149 /raid/cim_homes: Testing spare device/dev/hd/1.5.0/data
</verb>
<verb>939 secs: autorepair pid=1149 /raid/cim_homes: engaging hot spare ...
</verb>
<verb>939 secs: autorepair pid=1149 /raid/cim_homes: reconstructing drive 4 ...
</verb>
<verb>939 secs: 1054
</verb>
<verb>939 secs: Rebuild on /raid/cim_homes/repair: Max buffer 2800 in 7491 reads,
 priority 6 sleep 500
</verb>

The rebuild script will printout its progress every 10&percnt; of the job
 completed
<verb>939 secs: Rebuild on /raid/cim_homes/repair @ 0/7491
</verb>
<verb>1920 secs: Rebuild on /raid/cim_homes/repair @ 1498/7491
</verb>
<verb>2414 secs: Rebuild on /raid/cim_homes/repair @ 2247/7491
</verb>
<verb>2906 secs: Rebuild on /raid/cim_homes/repair @ 2996/7491
</verb>


<sect1>Re-integrating a repaired drive into the RAID (levels 3 and 5)
<p>

After you have replaced the bad drive you must re-integrate it into the
 RAID set using the following procedure.
<enum>
<item>Start the text GUI
<item>Look the list of backends for the RAID set(s).
<item>Backends that have been marked faulty will have a (-) to the right of their
 ID ( e.g. D1.1.0- ). 
<item>If you set up spares the ID of the faulty backend will be followed by the
 ID of the spare that has replaced it ( e.g. D1.1.0-D1.5.0 ) .
<item>Write down the ID(s) of the faulty backend(s) (NOT the spares).
<item>Press Q to exit agui
<item>At the husky prompt type:<tscreen>
<verb>replace &lt;name&gt; &lt;backend&gt; 
</verb></tscreen>
</enum>

Where &lt;name&gt; is whatever you named the raid set and &lt;backend&gt;
 is the ID of the backend that is being re-integrated into the RAID. If a spare
 was in use it will be automatically returned to the spares pool. Be patient,
 reconstruction can take a few minutes to several hours depending on
 the RAID level and the size. Fortunately, you can use the RAID as you normally
 would during this process. 


<sect>Troubleshooting / Error Messages
<p>
<sect1>Out of band temperature detected...
<p>
<itemize>
<item>Probable Cause: The 5070 SBUS card is not adequately cooled.
<item>Solution: Try to improve cooling inside the case. Clean dust from the fans,
 re-organize the cards so the raid card is closest to the fan, etc. On some
 of the &dquot;pizza box&dquot; sun cases (e.g. SPARC 20) you may need to add
 supplementary cooling fans especially if you have it loaded with cards.
</itemize>
<sect1>... failed ... cannot have more than 1 faulty backend.
<p>
<itemize>
<item>Cause: More than one backend in the RAID 3/4/5 has failed (i.e. there is
 no longer sufficient redundancy to enable the lost data to be reconstructed).
 
<item>Solution: You're hosed ... Sorry. 
If you did not assign spares when you
 configured you RAID 3/4/5 now may be a good time to re-consider the wisdom
 of that decision. Hopefully you have been making regular backups. Since now
 you will have to replace the defective drives, re-configure the RAID, and restore
 the data from a secondary source.
</itemize>
<sect1>When booting I see: ... Sun disklabel: bad magic 0000 ... unknown partition
 table.
<p>
<itemize>
<item>Suspected Cause: Incorrect settings in the disk label set by fdisk (or
 whatever partitioning utility you used). This message seems to happen when
 you choose one of the preset disk labels rather than &dquot;Custom with autoprobed
 defaults.&dquot;
<item>Solution: Since this error does not seem to effect the operation of the
 drive you can choose to do nothing and be ok. If you want to correct it you
 can try re-labeling the disk or re-partitioning the disk and choose &dquot;Custom
 with autoprobed defaults.&dquot; If you are installing RedHat Linux from scratch
 the installer will get all of this right for you.
</itemize>
<sect>Bugs
<p>

None yet! Please send bug reports to tdc3@psu.edu
<sect>Frequently Asked Questions
<p>
<sect1>How do I reset/erase the onboard configuration?
<p>

At the husky prompt issue the following command:
<verb>rconf -init
</verb>

This will delete all of the RAID configuration information but not the
 global variables and scsi monitors. the remove ALL configuration information
 type:
<verb>rconf -fullinit
</verb>

Use these commands with caution!
<sect1>How can I tell if a drive in my RAID has failed?
<p>

In the text GUI faulty backends appear with a (-) to the right of their
 ID. For example the list of backends:
<verb>D0.0.0,D1.0.0-,D2.0.0,D0.1.0,D1.1.0,D2.1.0
</verb>

Indicates that backend (drive) D1.0.0 is either faulty or not present.
 If you assigned spares (RAID 3 or 5) then you should also see that one or more
 spares are in use. Both the main and the and the RaidSets screens will show
 information on faulty/not present drives in a RAID set.

<sect>Advanced Topics: 5070 Command Reference
<p>

In addition to the text based GUI the RAID configuration may also be manipulated
 from the husky prompt ( the : raid; prompt) of the onboard controller. This
 section describes commands that a user can input interactively or via a script
 file to the K9 kernel. Since K9 is an ANSI C Application Programming Interface
 (API) a shell is needed to interpret user input and form output. Only one shell
 is currently available and it is called husky. The K9 kernel is modelled on
 the Plan 9 operating system whose design is discussed in several papers from
 AT&amp;T (See the &dquot;Further Reading&dquot; section for more information).
 K9 is a kernel targeted at embedded controllers of small to medium complexity
 (e.g. ISDN-ethernet bridges, RAID controllers, etc). It supports multiple lightweight
 processes (i.e. without memory management) on a single CPU with a non-pre-emptive
 scheduler. Device driver architecture is based on Plan 9 (and Unix SVR4) STREAMS.
 Concurrency control mechanisms include semaphores and signals. The husky shell
 is modelled on a scaled down Unix Bourne shell. 

Using the built-in commands the user can write new scripts thus extending
 the functionality of the 5070. The commands (adapted from the 5070 man pages)
 are extensive and are described below.

<sect1>AUTOBOOT - script to automatically create all raid sets and scsi monitors
<p>
<itemize>
<item>SYNOPSIS: autoboot
<item>DESCRIPTION: autoboot is a husky script which is typically executed when
 a RaidRunner boots. The following steps are taken -
<enum>
<item>Start all configured scsi monitor daemons (smon).
<item>Test to see if the total cache required by all the raid sets that are to
 boot is  not  more  than 90&percnt; of available memory.
<item>Start  all the scsi target daemons (stargd) and set each daemon's mode
 to &dquot;spinning-up&dquot; which enables it to respond to all non medium
 access commands from the host.  This  is  done  to  allow hosts to gain knowledge
 about the RaidRunner's scsi targets as quickly as possible.
<item>Bind into the root (ram) filesystem all unused spare backend devices.
<item>Build all raid sets.
<item>If  battery  backed-up  ram is present, check for any saved writes and
 restore them into the just built raid sets.
<item>Finally, set the state of all scsi target daemons to &dquot;spun-up&dquot;
 enabling hosts to fully access the raid set's behind them.
</enum>
</itemize>
</sect1>


<sect1>AUTOFAULT - script to automatically mark a backend faulty after a drive
 failure
<p>
<itemize>
<item>SYNOPSIS: autofault raidset
<item>DESCRIPTION: autofault  is  a  husky  script  which is typically executed
 by a raid file system upon the failure of a backend of that raid set when that
 raid file system cannot use spare backends or has been configured not to use
 spare backends. After parsing it's arguments (command and environment) autofault
 issues a rconf command to mark a given backend as faulty.
<item>OPTIONS: 
<itemize>
<item>raidset: The bind point of the raid set whose backend failed.
<item>&dollar;DRIVE_NUMBER: The index of the backend that failed. The first backend
 in a raid set is 0. This option is passed as an environment variable.
<item>&dollar;BLOCK_SIZE: The  raid set's io block size in bytes. (Ignored).
  This option is passed as an environment variable.
<item>&dollar;QUEUE_LENGTH: The raid set's queue length. (Ignored).  This option
 is passed as an environment variable.
</itemize>
<item>SEE ALSO: rconf
</itemize>
</sect1>


<sect1>AUTOREPAIR - script to automatically allocate a spare and reconstruct a
 raid set
<p>
<itemize>
<item>SYNOPSIS: autorepair raidset size
<item>DESCRIPTION: autorepair  is  a  husky script which is typically executed
 by either a raid type 1, 3 or 5 file system upon the failure of a backend of
 that raid set.
</itemize>

After parsing it's arguments (command and environment) autorepair gets
 a spare device from the  RaidRunner's  spares  spool.  It  then  engages  it
 in write-only mode and reads the complete raid device which reconstructs the
 data on the spare.  The read is from the raid file system  repair  entrypoint.
  Reading from  this  entrypoint  causes  a  read  of  a  block immediately
 followed by a write of that block. The read/write sequence is atomic (i.e is
 not interruptible).  Once the reconstruction has completed, a check is  made
 to ensure the spare did not fail during reconstruction and if not, the access
 mode of the spare device is set to the access mode of the raid set.  The process
  that  reads  the  repair  entrypoint  is rebuild.


This  device reconstruction will take anywhere from 10 minutes to one and
 a half hours depending on both the size and speed of the backends and the amount
 of activity the host is generating.


During device reconstruction, pairs of numbers will be  printed  indicating
  each  10&percnt;  of  data  reconstructed.  The pairs of numbers are separated
 by a slash character, the first number being the number of blocks reconstructed
 so far and the second being the number of blocks to be reconstructed.
 Further status about the rebuild can be gained from running rebuild.


When the spare is allocated both the number of spares currently used on
 the backend and the spare device name is printed. The number of spares on a
 backend is referred to the depth of spares  on  the  backend. Thus  prior 
 to  re-engaging the spare after a reconstruction a check can be made to see
 if the depth is the same. If it is not, then the spare reconstruction failed
 and reconstruction using another  spare  is underway (or no spares are available),
 and hence we don't re-engage the drive.

<itemize>
<item>OPTIONS: 
<itemize>
<item>raidset: The bind point of the raid set whose backend failed.
<item>size : The size of the raid set in 512 byte blocks.
<item>&dollar;DRIVE_NUMBER: The  index  of  the  backend  that  failed. The first
 backend in a raid set is 0.  This option is passed as an environment variable.
<item>&dollar;BLOCK_SIZE: The raid set's io block size in bytes.  This option
 is passed as an environment variable.
<item>&dollar;QUEUE_LENGTH: The raid set's queue length.  This option is passed
 as an environment variable.
</itemize>
<item>SEE ALSO: rconf, rebuild
</itemize>
</sect1>

<sect1>BIND - combine elements of the namespace 
<p>
<itemize>
<item>SYNOPSIS: bind &lsqb;-k&rsqb; new old
<item>DESCRIPTION: Bind replaces the existing old file (or directory) with the
 new file (or directory). If the&dquot;-k&dquot; switch is given then new must
 be a kernel recognized device (file system). Section 7k of the manual pages
 documents the devices (sometimes called file systems) that can be bound using
 the &dquot;-k&dquot; switch.
</itemize>
<sect1>BUZZER - get the state or turn on or off the buzzer 
<p>
<itemize>
<item>SYNOPSIS: buzzer or buzzer on|off|mute
<item>DESCRIPTION: Buzzer will either print the state of the buzzer, turn on
 or off the buzzer or mute it. If no arguments  are  given then the state of
 the buzzer is printed, that is on or off will be printed if the buzzer is currently
 on or off respectively. If the buzzer has been muted, then you will be informed
 of this. If the buzzer has not been used since the RaidRunner has booted then
 the special state, unused, is printed. If the argument on is given the buzzer
 is turned on, if off, the buzzer is turned off. If the argument mute is given
 then the muted state of the buzzer is changed. 
<item>SEE ALSO: warble, sos
</itemize>
<sect1>CACHE - display information about and delete cache ranges
<p>
<itemize>
<item>SYNOPSIS: cache &lsqb;-D moniker&rsqb; &lsqb;-I moniker&rsqb; &lsqb;-F&rsqb;
 &lsqb;-g moniker first|last&rsqb; lastoffset
<item>DESCRIPTION: cache  will  print (to standard output) information about
 the given cache range, delete a given cache range, flush the cache or return
 the last offset of all cache ranges.
<item>OPTIONS
<itemize>
<item>-F: Flush all cache buffers to their backends (typically raid sets).
<item>-D moniker: Delete the cache range with moniker (name) moniker.
<item>-I moniker: Invalidate the cache for the given cache range (moniker). This
 is only useful for debugging or elaborate  benchmarks.
<item>g moniker first|last: Print either the first or last block number of a
 cache range with moniker (name) moniker.
<item>lastoffset: Print the last offset of all cache ranges. The last offset
 is the last block number of all cache ranges.
</itemize>
</itemize>
<sect1>CACHEDUMP - Dump the contents of the write cache to battery backed-up ram
<p>
<itemize>
<item>SYNOPSIS: cachedump
<item>DESCRIPTION: cachedump causes all unwritten data in the RaidRunner's cache
 to be written out to the battery backed-up ram. No data will be written to
 battery backed-up ram if there is currently valid  data  already  stored there.
 This command is typically executed when there is something wrong with the data
 (or it's organization) in battery backed-up ram and you need to re-initialize
 it. cachedump will always return a NULL status.
<item>SEE ALSO: showbat, cacherestore
</itemize>
<sect1>CACHERESTORE - Load the cache with data from battery backed-up ram
<p>
<itemize>
<item>SYNOPSIS: cacherestore
<item>DESCRIPTION: cacherestore will check the RaidRunner's battery backed-up
 ram for any data it has stored as a result of a power failure. It will copy
 any data directly into the cache. This command is typically executed automatically
 at boot time and prior to the  RaidRunner  making  it's data available to a
 host. Having successfully copied any data from battery backed-up ram into the
 cache, it flushes the cache and then re-initializes battery backed-up ram to
 indicate it holds no data. cacherestore will return a NULL status on success
 or 1 if an error occurred during the loading  (with  a message written to standard
 error).
<item>SEE ALSO: showbat
</itemize>
<sect1>CAT - concatenate files and print on the standard output
<p>
<itemize>
<item>SYNOPSIS: cat &lsqb; file... &rsqb;
<item>DESCRIPTION: cat writes the contents of each given file, or standard input
 if none are given or when a file named `-' is given, to standard output. If
 the nominated file is a directory then the filenames contained in that directory
 are sent to standard out (one per line). More information on a file (e.g. its
 size) can be obtained by using stat. The script file ls uses cat and stat to
 produce directory listings.
<item>SEE ALSO echo, ls, stat
</itemize>
</sect1>

<sect1>CMP - compare the contents of 2 files
<p>
<itemize>
<item>SYNOPSIS: cmp &lsqb;-b blockSize&rsqb; &lsqb;-c count&rsqb; &lsqb;-e&rsqb;
 &lsqb;-x&rsqb; file1 file2
<item>DESCRIPTION: cmp compares the contents of the 2 named files. If file1 is
 &dquot;-&dquot; then standard input is used for that file. If the files are
 the same length and contain the same val<61> ues then nothing is written to standard
 output and the exit status NIL (i.e. true) is set. Where the 2 files dif<69> fer,
 the first bytes that differ and the position are out<75> put to standard out and
 the exit status is set to &dquot;differ&dquot; (i.e. false). The position is
 given by a block number (origin 0) followed by a byte offset within that block
 (origin 0). The optional &dquot;-b&dquot; switch allows the blockSize of each
 read operation to be set. The default blockSize is 512 (bytes). For big compares
 involving disks a relatively large blockSize may be useful (e.g. 64k). See
 suffix for allowable suffixes. The optional &dquot;-c&dquot; switch allows
 the count of blocks read to fixed. A value of 0 for count is interpreted as
 read to the end of file (EOF). To compare the first 64 Megabytes of 2 files
 the switches &dquot;-b 64k -c 1k&dquot; could be used. See suffix for allowable
 suffixes. The optional &dquot;-e&dquot; switch instructs ccmmpp to output to
 stan<61> dard out (usually overwriting the same line) the count of blocks compared,
 each time a multiple of 100 is reached. The final block count is also output.
 The optional &dquot;-x&dquot; switch instructs ccmmpp to continue after a comparison
 error (but not a file error) and keep a count of blocks in error. If any errors
 are detected only the last one will be output when the command exits. If the
 &dquot;-e&dquot; switch is also given then the current count of blocks in error
 is output to the right of the multiple of 100 blocks compared. This command
 is designed to compare very large files. Two buffers of blockSize are allocated
 dynamically so their size is bounded by the amount of memory (i.e. RAM in the
 target) available at the time of command execution. The count could be up to
 2G. The number of bytes compared is the product of blockSize and count (i.e.
 big enough).
<item>SEE ALSO: suffix
</itemize>
<sect1>CONS - console device for Husky
<p>
<itemize>
<item>SYNOPSIS: bind -k cons bind_point
<item>DESCRIPTION: cons  allows  an interpreter (e.g. Husky) to route console
 input and output to an appropriate device. That console input and output is
 available at bind_point in the K9 namespace. The special file cons should always
 be available.
<item>EXAMPLES: Husky does the following in its initialisation:
</itemize>

<tscreen>
<verb>bind -k cons /dev/cons
</verb></tscreen>

On a Unix system this is equivalent to:
<verb>bind -k unixfd /dev/cons
</verb>

On a DOS system this is equivalent to:
<verb>bind -k doscon /dev/cons
</verb>

On target hardware using a SCN2681 chip this is equivalent to:
<verb>bind -k scn2681 /dev/cons
</verb>

<itemize>
<item>SEE ALSO: unixfd, doscon, scn2681
</itemize>
</sect1>

<sect1>DD - copy a file (disk, etc)
<p>
<itemize>
<item>SYNOPSIS: dd &lsqb;if=file&rsqb; &lsqb;of=file&rsqb; &lsqb;ibs=bytes&rsqb;
 &lsqb;obs=bytes&rsqb; &lsqb;bs=bytes&rsqb; &lsqb;skip=blocks&rsqb; &lsqb;seek=blocks&rsqb;
 &lsqb;count=blocks&rsqb; &lsqb;flags=verbose&rsqb;
<item>DESCRIPTION: dd copies a file (from the standard input to the standard
 output, by default) with a user-selectable blocksize.
<item>OPTIONS
<itemize>
<item>if=file Read from file instead of the standard input.
<item>of=file, Write to file instead of the standard output. 
<item>ibs=bytes, Read given number of bytes at a time.
<item>obs=bytes, Write given number of bytes at a time.
<item>bs=bytes, Read and write given number of bytes at a time. Override ibs
 and obs.
<item>skip=blocks, Skip ibs-sized blocks at start of input.
<item>seek=blocks, By-pass obs-sized blocks at start of output.
<item>count=blocks, Copy only ibs-sized input blocks.
<item>flags=verbose, Print (to standard output) the number of blocks copied every
 ten percent of the copy. The output is of the form X/T where X is the number
 of blocks copied so far and T is the total number of blocks to copy. This option
 can only be used if both the count= and of= options  are also given.
</itemize>

The decimal numbers given to &dquot;ibs&dquot;, &dquot;obs&dquot;, &dquot;bs&dquot;,
 &dquot;skip&dquot;, &dquot;seek&dquot; and &dquot;count&dquot; must not be
 negative. These numbers can optionally have a suffix (see suffix). dd outputs
 to standard out in all cases. A successful copy of 8 (full) blocks would cause
 the following output:
<verb>8+0 records in
</verb>
<verb>8+0 records out
</verb>
</itemize>

The number after the &dquot;+&dquot; is the number of fractional blocks
 (i.e. blocks that are less than the block size) involved. This number will
 usually be zero (and is otherwise when physical media with alignment requirements
 is involved).


A write failure outputting the last block on the previous example would
 cause the following output:
<verb>Write failed
</verb>
<verb>8+0 records in
</verb>
<verb>7+0 records out
</verb>
<itemize>
<item>SEE ALSO: suffix
</itemize>
<sect1>DEVSCMP - Compare a file's size against a given value
<p>
<itemize>
<item>SYNOPSIS: devscmp filename size
<item>DESCRIPTION: devscmp will find the size of the given file and compare it's
 size in 512-byte blocks to the given size (to be in 512-byte blocks).  If the
 size of the file is less than the given value, then -1 is printed, if equal
 to then 0 is printed, and if the size of the given file is greater than the
 given size then 1 is printed. This routine is used in internal scripts to ensure
 that backends of raid sets are of an appropriate size.
</itemize>
<sect1>DFORMAT- Perform formatting functions on a backend disk drive
<p>
<itemize>
<item>SYNOPSIS
<itemize>
<item>dformat -p c.s.l -R bnum
<item>dformat -p c.s.l -pdA|-pdP|-pdG
<item>dformat -p c.s.l -S &lsqb;-v&rsqb; &lsqb;-B firstbn&rsqb;
<item>dformat -p c.s.l -F
<item>dformat -p c.s.l -D file
</itemize>
<item>DESCRIPTION: In it's first form dformat will either reassign a block on
 a nominated disk drive.  via the SCSI-2 REASSIGN BLOCKS command. The second
 form will allow you to print out the current manufacturers  defect  list  (-pdP),
  the  grown defect  list (-pdG) or both defect lists (-pdA). Each printed list
 is sorted with one defect per line in Physical Sector Format - Cylinder Number,
 Head Number and Defect Sector Number. The third form causes the drive to be
 scanned in a destructive write/read/compare manner. If a  read  or write  or
  data comparison error occurs then an attempt is made to identify the bad sector(s).
 Typically the drive is scanned from block 0 to the last block on the drive.
 You can optionally give an alternative starting block number. The fourth form
 causes a low level format on the specified device. The fifth option allows
 you to download a device's microcode into the device.
<item>OPTIONS:
<itemize>
<item>-R bnum: Specify a logical block number to reassign to the drive's grown
 defect list.
<item>-pdA: Print both the manufacturer's and grown defect list.
<item>\ -pdP: Print the manufacturer's defect list.
<item>-pdG: Print the grown defect list.
<item>-S: Perform a destructive scan of the disk reporting I/O errors.
<item>-B firstbn: Specify the first logical block number to start a scan from.
<item>-v: Turn on verbose mode - which prints the current block number being
 scanned.
<item>-F: Issue a low-level SCSI format command to the given device. This will
 take some time.
<item>-D file: Download  into  the  specified device, the given file. The download
 is effected by a single SCSI Write-Buffer command in save microcode mode. This
 allows users to update  a  device's  microcode. Use this command carefully
 as you could destroy the device by loading an incorrect file.
<item>-p c.s.l: Identify  the disk device by specifying it's channel, SCSI ID
 (rank) and SCSI LUN provided in the format &dquot;c.s.l&dquot;
</itemize>
<item>SEE ALSO: Product manual for disk drives used in your RAID.
</itemize>
<sect1>DIAGS - script to run a diagnostic on a given device
<p>
<itemize>
<item>SYNOPSIS: diags disk -C count -L length -M io-mode -T io-type -D device
<item>DESCRIPTION: diags is a husky script which is used to run the randio diagnostic
 on a given device. When randio is executed, it is executed in verbose mode.
<item>OPTIONS:
<itemize>
<item>disk: This is the device type of diagnostic we are to run.
<item>-C count: Specify the number of times to execute the diagnostic.
<item>-L length: Specify  the  &dquot;length&dquot; of the diagnostic to execute.
 This can be either short, medium or long and specified with the letter's s,
 m or l respectively. In the case of a disk, a short test will  the first 10&percnt;
 of the device, a medium the first 50&percnt; and long the whole (100&percnt;)
 of the disk.
<item>-M io-mode: Specify a destructive (read-write) or non-destructive (read-only)
 test.  Use either read-write or read-only.
<item>-T io-type: Specify a type of io - either sequential or random.
<item>-D device: Specify the device to test.
</itemize>
<item>SEE ALSO: randio, scsihdfs
</itemize>
<sect1>DPART - edit a scsihd disk partition table
<p>
<itemize>
<item>SYNOPSIS: 
<itemize>
<item>dpart -a|d|l|m -D file &lsqb;-N name&rsqb; &lsqb;-F firstblock&rsqb; &lsqb;-L
 lastblock&rsqb;
<item>dpart -a -D file -N name -F firstblock -L lastblock
<item>dpart -d -D file -N name
<item>dpart -l -D file
<item>dpart -m -D file -N name -F firstblock -L lastblock
</itemize>
<item>DESCRIPTION: Each  scsihd device  (typically a SCSI disk drive) can be
 divided up into eight logical partitions. By default when a scsihd device is
 bound into the RaidRunner's file system, it has four  partitions, the  whole
  device  (raw),  typically named bindpoint/raw, the partition file (bindpoint/partition),
 the RaidRunner backup configuration file (bindpoint/rconfig), and the &dquot;data&dquot;
 portion of the disk (bind- point/data) which represents the whole device less
 the backup configuration area and partition file. For more information, see
 scsihdfs. If other partitions are added, then they will appear as bindpoint/partitionname.
 dpart allows you to edit or list the partition table on a scsihd device (typically
 a disk).
<item>OPTIONS:
<itemize>
<item>-a: Add a partition. When adding a partition, you need to specify the partition
  name  (-N)  and  the partition range from the first block (-F) to the last
 block (-L).
<item>-d: Delete a named (-N) partition.
<item>-l: List all partitions.
<item>-m: Modify an existing partition.  You  will need to specify the partition
 name (-N) and BOTH it's first (-F) and last (-L) blocknumbers even if you are
 just modifying the last block number.
<item>-D file: Specify the partition file to be edited. Typically, this is the
 bindpoint/partition file.
<item>-N name: Specify the partition name.
<item>-F firstblock: Specify the first block number of the partition.
<item>-L lastblock: Specify the last block number of the partition.
</itemize>
<item>SEE ALSO: scsihd
</itemize>
<sect1>DUP - open file descriptor device
<p>
<itemize>
<item>SYNOPSIS: bind -k dup bind_point
<item>DESCRIPTION: The dup device makes a one level directory with an entry in
 that directory for every open file descriptor of the invoking K9 process. These
 directory &dquot;entries&dquot; are the numbers. Thus a typical process (script)
 binding a dup device would at least make these files in the namespace: &dquot;bind_point/0&dquot;,
 &dquot;bind_point/1&dquot; and &dquot;bind_point/2&dquot;. These would correspond
 to its open standard in, standard out and standard error file descriptors.
 A dup device allows other K9 processes to access the open file descriptors
 of the invoking process. To  do  this  the  other processes  simply  &dquot;open&dquot;
  the  required  dup  device directory entry whose name (a number) corresponds
 to the required file descriptor.
</itemize>
<sect1>ECHO - display a line of text
<p>
<itemize>
<item>SYNOPSIS: echo &lsqb;string ...&rsqb;
<item>DESCRIPTION: echo writes each given string to the standard output, with
 a space between them and a newline after the last one. Note that all the string
 arguments are written in a single write kernel call. The following backslash-escaped
 characters in the strings are converted as follows:

<itemize>
<item>\b     backspace
<item>\c     suppress trailing newline
<item>\f     form feed
<item>\n     new line
<item>\r     carriage return
<item>\t     horizontal tab
<item>\v     vertical tab
<item>\\     backslash
</itemize>

\nnn   the character whose ASCII code is nnn (octal)
</itemize>
<itemize>
<item>SEE ALSO: cat
</itemize>
<sect1>ENV- environment variables file system
<p>
<itemize>
<item>SYNOPSIS: bind -k env bind_point
<item>DESCRIPTION: env file system associates a one level directory with the
 bind_point in the K9 namespace. Each file name in that directory is the name
 of the environment variable while the contents of the file is that variable's
 current value. Conceptually each process sees their own copy of the env file
 system.  This copy is either empty or inherited from this process's parent
 at spawn time (depending on the flags to spawn).
</itemize>


<sect1>ENVIRON - RaidRunner Global environment variables - names and effects
<p>
<itemize>
<item>DESCRIPTION: The RaidRunner uses GLOBAL environment variables to control
 the functionality of automatic actions. GLOBAL environment variables are saved
 in the Raid configuration area so they retain their values between reboots/power
 downs. Certain RaidRunner internal run-time variables can also be set as a
 GLOBAL environment variables. See the internals manual entry for details. The
 table below describes those GLOBAL environment variables that are used by the
 RaidRunner in it's normal operation.
<itemize>
<item>RebuildPri

This  variable,  if  set, controls the priority used when drive reconstruction
 occurs via the rebuild program. If the variable is not set then the default
 rebuild priority would be used. The variable is to be a comma separated list
 of raid set names and their  associated  rebuild  priorities  and  sleep periods
 (colon separated). The form is
<verb>Rname_1:Pri_1:Sleep_1,Rname_2:Pri_2:Sleep_2,...,Rname_N:Pri_N:Sleep_N
</verb>

where  Pri_1  is  to  be  the priority the rebuild program runs with when
 run on raid set Rname_1, Sleep_1 is the period, in milliseconds, to sleep between
 each rebuild action on the raid set, Pri_2 is to be the priority  for  raid
 set Rname_2, and so forth.  For example, if the value of RebuildPri is
<verb>R:5:30000
</verb>

then if a rebuild occurs (via replace, repair or autorepair) on raid set
 R then the rebuild will run with priority 5 (via the -p rebuild option) and
 will sleep 30000 milliseconds (30 seconds) between each rebuild action (specified
 via the -S rebuild option). The priority given must be valid for the rebuild
 program.

<item>BackendRanks

On  certain  RaidRunner's where multiple controllers may exist, you can
 restrict a controller's access to the backend ranks of devices available. 
 For example, you may have 2 controllers and 4 ranks of backend devices. You
 can  specify that  the  first controller can only access the first two ranks
 and the second controller, the second two ranks. This variable along with other
 associated commands allows you to set up this restriction. Additionally, you
 may only have a single controller RaidRunner which is in  an  enclosure  with
  multiple  ranks.  By default  the controller will attempt to probe for all
 devices on all ranks. If you have only populated the RaidRunner with say, half
 it's possible compliment of backend devices, then the RaidRunner will still
 probe for the other  half. Setting this variable appropriately will prevent
 this un-needed (and on occasion time consuming) process. This variable takes
 the form
<verb>controller_id:ranklist controller_id:ranklist ...
</verb>


where controller_id is the controller number (from 0 upwards) and ranklist
 is a comma list of backend ranks which the given controller will access. Note
 that the backend rank is the scsi-id of that rank. For example, on a 2 rank
 (rank 1 and 2 - i.e scsi id 1 for the first rank and scsi id 2 for the second),
 1  controller 


This variable takes the form


For example, on a 2 rank (rank 1 and 2 - i.e scsi id 1 for the first rank
 and scsi id 2 for the second), 1  controller RaidRunner  where  only  the 
 first  rank  has devices you could prevent the controller from attempting to
 access the (empty) second rank by setting BackendRanks to
<verb>0:1
</verb>


Typically, you would not set this variable directly, but use supporting
  commands  to  set  it.  These  commands  are pranks and sranks. See these
 manual entries for details.

</itemize>
<item>RAIDn_reference_PBUFS

Raid  types 3, 4 and 5 all make use of memory for temporary parity buffers
 when they need to create parity data. This memory is in addition to that allocated
 to a raid set's cache.  When a raid set is created, it  will  also  create
  a default  number  of  parity buffers (which are the same size is a raid set's
 iosize). Sometimes, if the iosize of the raid set is large there will not be
 enough memory to create this default number of parity buffers.  To overcome
  this situation, you can set GLOBAL environment variables to over-ride the
 default number of parity buffers that all raid sets of a particular type or
 a specific raid set will use. You need to set these variables before you define
 the raid set  via  agui and if you delete them and not the raid set, then the
 effect raid sets may not boot and hence will not be accessible by a host. The
 variables are of the form RAIDn_reference_PBUFS where n is the raid type (3,
 4 or 5), and reference  is the raid set's name or the string 'Default' You
 use the reference of 'Default' to specify all raid sets of a particular type.
 For example, to over-ride the number of parity buffers for a raid 5 named
<verb>: raid ; setenv RAID5_FRED_PBUFS 64
</verb>
</itemize>

To over-ride the number of parity buffers for ALL raid 3's (and set only
 72 parity buffers) set
<verb>: raid ; setenv RAID3_Default_PBUFS 128
</verb>


If you set a default for all raid sets of a particular type, but want ONE
 of them to be different then set up a  variable  for that  particular  raid
 set as it's value will over-ride the default. In the above example, where all
 Raid Type 3 will have 128 parity buffers, you could set the variable
<verb>: raid ; setenv RAID3_Dbase_PBUFS 56 
</verb>


which will allow the raid 3 raid set named 'Dbase' to have 56 parity buffers,
 but all other raid 3's defined on the RaidRunner will have 128.

<itemize>
<item>SEE ALSO: setenv, printenv, rconf, rebuild, internals
</itemize>
</sect1>

<sect1>EXEC - cause arguments to be executed in place of this shell
<p>
<itemize>
<item>SYNOPSIS: exec &lsqb; arg ... &rsqb;
<item>DESCRIPTION: exec causes the command specified by the first arg to be executed
 in place of this shell without creating a new process.  Subsequent args are
 passed to the command specified by the first arg as its arguments. Shell redirection
 may appear and, if no other arguments are given, causes the shell input/output
 to be modified. 
</itemize>
<sect1>EXIT - exit a K9 process
<p>
<itemize>
<item>SYNOPSIS: exit &lsqb;string&rsqb;
<item>DESCRIPTION: exit has an optional string argument. If the optional argument
 is given the current K9 process is terminated with the given string as its
 exit value. (If the string has embedded spaces then the whole string should
 be a quoted_string). If no argument is given then the shell gets the string
 associated with the environment variable &dquot;status&dquot; and returns that
 string as the exit value. If the environment variable &dquot;status&dquot;
 is not found then the &dquot;true&dquot; exit status (i.e. NIL) is returned.
<item>SEE ALSO: true, K9exit
</itemize>
<sect1>EXPR - evaluation of numeric expressions
<p>
<itemize>
<item>SYNOPSIS: expr numeric_expr ... 
<item>DESCRIPTION: expr evaluates each numeric_expr command line argument as
 a separate numeric expression. Thus a single expression cannot contain unescaped
 whitespaces or needs to be placed in a quoted string (i.e.  between &dquot;&lcub;&dquot;
 and &dquot;&rcub;&dquot;). Arithmetic is performed on signed integers (currently
 numbers in the range from -2,147,483,648 to 2,147,483,647). Successful calculations
  cause no output (to either standard out/error or environment variables). So
 each useful numeric_expr needs to include an assignment (or op-assignment).
 Each numeric_expr argument supplied is evaluated in the order given (i.e. left
 to right) until they all evaluate successfully (returning a true status). If
 evaluating a numeric_expr fails (usually due to a syntax error) then the expr
 command fails with &dquot;error&dquot; as the exit status and the error message
 is written to the environment variable &dquot;error&dquot;.
<item>OPERATORS: The precedence of each operator is shown following the description
 in square brackets. &dquot;0&dquot; is the highest precedence. Within a single
 precedence group evaluation is left-to-right except for assignment operators
 which are right-to-left. Parentheses have higher precedence than all operators
 and can be used to change the default precedence shown below.

UNARY OPERATORS

<itemize>
<item><verb>+</verb> Does nothing to expression/number to the right.
<item><verb>-</verb> negates expression/number to the right.
<item><verb>!</verb> logically negate expression/number to the right.
<item><verb>&tilde;</verb> Bitwise negate expression/number to the right.

</itemize>

BINARY ARITHMETIC OPERATORS
<itemize>
<item><verb>*</verb> Multiply enclosing expressions &lsqb;2&rsqb;
<item><verb>/</verb> Integer division of enclosing expressions 
<item><verb>&percnt;</verb> Modulus of enclosing expressions.
<item><verb>+</verb> Add enclosing expressions 
<item><verb>-</verb> Subtract enclosing expressions. 
<item><verb>&lt;&lt;</verb> Shift left expression _left_ by number in right expression. Equivalent to: left * (2 ** right)
<item><verb>&gt;&gt;</verb> Shift left expression _right_ by number in right expression. Equivalent to: left / (2 ** right) 
<item><verb>&amp;</verb> Bitwise AND of enclosing expressions 
<item><verb>^</verb> Bitwise exclusive OR of enclosing expressions. &lsqb;8&rsqb;
<item><verb>|</verb> Bitwise OR of enclosing expressions. &lsqb;9&rsqb;
</itemize>

BINARY LOGICAL OPERATORS

These logical operators yield the number 1 for a true comparison and 0
 for a false comparison. For logical ANDs and ORs their left and right expressions
 are assumed  to be false if 0 otherwise true. Both logical ANDs and ORs evaluate
 both their left and right expressions in all case (cf. C's short-circuit action).

<itemize>

<item><verb>&lt;=</verb> true when left less than or equal to right. &lsqb;5&rsqb;
<item><verb>&gt;=</verb> true when left greater than or equal to right. &lsqb;5&rsqb;
<item><verb>&lt;</verb> true when left less than right. &lsqb;5&rsqb;
<item><verb>&gt;</verb> true when left greater than right. &lsqb;5&rsqb;
<item><verb>==</verb> true when left equal to right. &lsqb;6&rsqb;
<item><verb>!=</verb> true when left not equal to right. &lsqb;6&rsqb;
<item><verb>&amp;&amp;</verb> logical AND of enclosing expressions &lsqb;10&rsqb;
<item><verb>||</verb> logical OR of enclosing expressions &lsqb;11&rsqb;
</itemize>

ASSIGNMENT OPERATORS

In the following descriptions &dquot;n&dquot; is an environment variable
 while &dquot;r_exp&dquot; is an expression to the right. All assignment operators
 have the same precedence which is lower than all other operators. N.B. Multiple
 assignment operators group right-to-left (i.e. same as C language).

<itemize>
<item><verb>=</verb> Assign right expression into environment variable on left.
<item><verb>*=</verb> n *= r_exp is equivalent to: n = n * r_exp
<item><verb>/=</verb> n /= r_exp is equivalent to: n = n / r_exp
<item><verb>&percnt;=</verb> n &percnt;= r_exp is equivalent to: n = n &percnt; r_exp
<item><verb>+=</verb> n += r_exp is equivalent to: n = n + r_exp
<item><verb>-=</verb> n -= r_exp is equivalent to: n = n - r_exp
<item><verb>&lt;&lt;=</verb> n &lt;&lt;= r_exp is equivalent to: n = n &lt;&lt; r_exp
<item><verb>&gt;&gt;=</verb> n &gt;&gt;= r_exp is equivalent to: n = n &gt;&gt; r_exp
<item><verb>&amp;=</verb> n &amp;= r_exp is equivalent to: n = n &amp; r_exp
<item><verb>|=</verb> n |= r_exp is equivalent to: n = n | r_exp
</itemize>

<item>NUMBERS: All number are signed integers in the range stated in the description
 above. Numbers can be input in base 2 through to base 36. Base 10 is the default
 base. The default base can be overridden by:
<enum>
<item>a leading &dquot;0&dquot; : implies octal or hexadecimal
<item>a number of the form _base_&num;_num_
</enum>

Numbers prefixed with &dquot;0&dquot; are interpreted as octal. Numbers
 prefixed with &dquot;0x&dquot; or &dquot;0X&dquot; are interpreted as hexadecimal.
  For  numbers  using the &dquot;&num;&dquot; notation the _base_ must be in
 the range 2 through to 36 inclusive. For bases greater then 10 the letters
 &dquot;a&dquot; through &dquot;z&dquot; are utilised for the extra &dquot;digits&dquot;.
 Upper and lower case letters are acceptable. Any single digit that exceeds
 (or is equal to) the base is consider an error. Base 10 numbers only may have
 a suffix. See suffix for a list of valid suffixes. Also note that since expr
 uses signed integers then &dquot;1G&dquot; is the largest magnitude number
 that can be represented with the &dquot;Gigabyte&dquot; suffix (assuming 32
 bit signed integers, -2G is invalid due to the order of evaluation).


<item>VARIABLES: The only symbolic variables allowed are K9 environment variables.
  Regardless of whether they are being read or written they should never appear
 preceded by a &dquot;&dollar;&dquot;. Environment variables that didn't previous
 exist that appear as left argument of an assignment are created. When a non-existent
 environment variable is read then it is interpreted as the value 0.
<item>EXAMPLES: Some simple examples:<tscreen>
expr &lcub;n = 1 + 2&rcub; &num; create n
echo &dollar;n
3
expr &lcub;n*=2&rcub; &num; 3 * 2 result back into n
echo &dollar;n
6
expr &lcub; k = n &gt; 5 &rcub; &num; 6 &gt; 5 is true so create k = 1
echo &dollar;k
1</tscreen>
<item>NOTE: expr is a Husky &dquot;built-in&dquot; command. See the &dquot;Note&dquot;
 section in &dquot;set&dquot; to see the implications.
<item>SEE ALSO: husky, set, suffix, test
</itemize>
</sect1>

<sect1>FALSE - returns the K9 false status
<p>
<itemize>
<item>SYNOPSIS: false
<item>DESCRIPTION: false does nothing other than return a K9 false status. K9
 processes return a pointer to a C string (null terminated array of characters)
 on termination. If that pointer is NULL then a true exit value is assumed while
 all other returned pointer values are interpreted  as false (with the string
 being some explanation of what went wrong). This command returns a pointer
 to the string &dquot;false&dquot; as its return value.
<item>EXAMPLE: The following script fragment will print &dquot;got here&dquot;
 to standard out:<tscreen>
<verb>if false then
</verb></tscreen>
<verb>echo impossible
</verb>
<verb>else
</verb>
<verb>echo got here
</verb>
<verb>end
</verb>
<item>SEE ALSO: true
</itemize>
<sect1>FIFO - bi-directional fifo buffer of fixed size
<p>
<itemize>
<item>SYNOPSIS:
<itemize>
<item>bind -k &lcub;fifo size&rcub; bind_point
<item>cat bind_point
<item>bind_point/data
<item>bind_point/ctl
</itemize>
<item>DESCRIPTION: fifo  file system associates a one level directory with the
 bind_point in the K9 namespace with a buffer size of size bytes. bind_point/data
 and bind_point/ctl are the data and control channels for the fifo. Data written
 to the bind_point/data file is available for reading from the same file in
 a first-in first-out basis. A write of x bytes to the bind_point/data file
 will either complete and transfer all the data, or will  transfer  sufficient
 bytes until the fifo buffer is full then block until data is removed from the
 fifo buffer by reading. A read of x bytes from the bind_point/data file will
 transfer the lessor of the current amount of data in the fifo buffer or x bytes.
 A read from the bind_point/ctl will return the size of the fifo buffer and
 the current usage. The number of opens (&num;  Opens) is the number of processes
 that currently have the bind_point/data file open.
<item>EXAMPLE<tscreen>
<verb>&gt; /buffer
</verb></tscreen>
<verb>bind -k &lcub;fifo 2048&rcub; /buffer
</verb>
<verb>ls -l /buffer
</verb>
<verb>/buffer:
</verb>
<verb>/buffer/ctl                     fifo    2 0x00000001    1 0
</verb>
<verb>/buffer/data                    fifo    2 0x00000002    1 0
</verb>
<verb>cat /buffer/ctl
</verb>
<verb>Max: 2048 Cur: 0, &num; Opens: 0
</verb>
<verb>echo hello &gt; /buffer/data
</verb>
<verb>cat /buffer/ctl
</verb>
<verb>Max: 2048 Cur: 6, &num; Opens: 0
</verb>
<verb>dd if=/buffer/data bs=512 count=1
</verb>
<verb>hello
</verb>
<verb>0+1 records in
</verb>
<verb>0+1 records out
</verb>
<verb>cat /buffer/ctl
</verb>
<verb>Max: 2048 Cur: 0, &num; Opens: 0
</verb>
<item>SEE ALSO: pipe
</itemize>
<sect1>GET - select one value from list
<p>
<itemize>
<item>SYNOPSIS: get number &lsqb; value ... &rsqb;
<item>DESCRIPTION: get uses the given number to select one value from the given
 list. Indexing is origin 0 (e.g. &dquot;get 0 aaa bb c&dquot; returns &dquot;aaa&dquot;).
 If the number is out of range for an index on the given list of values then
 nothing is returned. 
</itemize>
<sect1>GETIV - get the value an internal RaidRunner variable
<p>
<itemize>
<item>SYNOPSIS: 
<itemize>
<item>getiv
<item>getiv name
</itemize>
<item>DESCRIPTION: getiv prints the current value of an internal RaidRunner variable
 or prints a list of all variables. When a variable name is given it's current
 value is printed. If no value is given the all available internal variables
 are listed.
<item>NOTES: As different models of RaidRunners have different internal variables
 see your RaidRunner's Hardware Reference manual for a list of variables together
 with the meaning of their values. These variables are run-time variables and
 hence revert to their default value whenever  the  RaidRunner is booted.
<item>SEE ALSO: setiv
</itemize>
<sect1>HELP - print a list of commands and their synopses
<p>
<itemize>
<item>SYNOPSIS: help or ?
<item>DESCRIPTION: help or the question mark character - ?, will print a list
 of all commands available to the command interpreter. Along with each command,
 it's synopsis is printed.
</itemize>
<sect1>HUSKY - shell for K9 kernel
<p>
<itemize>
<item>SYNOPSIS
<itemize>
<item>husky &lsqb;-c command&rsqb; &lsqb; file &lsqb; arg ... &rsqb; &rsqb;
<item>hs &lsqb;-c command&rsqb; &lsqb; file &lsqb; arg ... &rsqb; &rsqb;
</itemize>
<item>DESCRIPTION: husky and hs are synonyms. husky is a command language interpreter
 that executes commands read from the standard input or from a file. husky is
 a scaled down model of Unix's Bourne shell (sh). One major difference is that
 husky has no concept of current working directory. If the &dquot;-c&dquot;
 switch is present then the following command is interpreted by husky in a newly
 thrown shell nested in the current environment. This newly thrown shell exits
 back to the current environment when the command finishes. Otherwise if arguments
 are given the first one is assumed to be a file containing husky commands.
 Again a new shell is thrown to execute these commands. husky script files can
 access their command line arguments and the 2nd and subsequent arguments to
 husky (if present) are passed to the file for that purpose. If no arguments
 are given to husky then commands are read from standard in (and the shell is
 considered interactive).
<item>RETURN STATUS: husky places the K9 return status of a process (NIL if ok,
 otherwise a string explaining the error) in the file &dquot;/env/status&dquot;

An example:
<verb>dd if=/xx
</verb>
<verb>dd: could not open /xx
</verb>
<verb>cat /env/status
</verb>
<verb>open failed
</verb>
<verb>cat /env/status
</verb>
<verb>&num; empty because previous &dquot;cat&dquot; worked
</verb>

As the file &dquot;/env/status&dquot; is an environment variable the return
 status of a command is also available in the variable &dollar;status. The exit
 status of a pipeline is the exit status of the last command in the pipeline.
</itemize>
<itemize>
<item>SIGNALS If an interactive shell receives an interrupt signal (i.e. K9_SIGINT
 - usually a control-C on the console) then the shell exits. The &dquot;init&dquot;
 process will then start a new instance of the husky shell with all the previously
 running processes (with the exception of the just killed shell) still running.
 This allows the user to kill the process that caused the previous shell problems.
 Alternatively a process that is acci<63> dentally run in foreground is effectively
 put in the background by sending an interrupt signal to the shell. Note that
 this is quite different to Unix shells which would forward the signal onto
 the foreground process.
<item>QUOTES, ESCAPING, STRING CONCATENATION, ETC: A quoted_string (as defined
 in the grammar) commences with a &dquot;&lcub;&dquot; and finishes with the
 matching &dquot;&rcub;&dquot;. The term &dquot;matching&dquot;  implies  that
  all embedded &dquot;&lcub;&dquot; must have a corresponding embedded &dquot;&rcub;&dquot;
 before the final &dquot;&rcub;&dquot; is said to match the original &dquot;&lcub;&dquot;.
 A quoted_string can be spread across several lines. No command line substitution
 occurs within quoted_strings. The character for escaping the following character
 is &dquot;\&dquot;. If a &dquot;&lcub;&dquot; needs to be interpreted literally
 then it can be represented by &dquot;\&lcub;&dquot;. If a string containing
  spaces (whitespaces) needs to be interpreted as a single token then space
 (whitespace) can be escaped (i.e. &dquot;\ &dquot;).  If a &dquot;\&dquot;
 itself needs to be interpreted literally then it can be represented by &dquot;\\&dquot;.
 The string concatenation character is &dquot;^&dquot;. This is useful when
 a token such as &dquot;/d4&dquot; needs to built up by a script when &dquot;/d&dquot;
 is  fixed  and  the &dquot;4&dquot; is derived from some variable:<tscreen>
<verb>set n 4
</verb></tscreen>
<verb>&gt; /d^&dollar;n
</verb>


This example would create the file &dquot;/d4&dquot;.


The output of another husky command or script can be made available inline
 by starting the sequence with &dquot;`&dquot; and finishing it with a &dquot;'&dquot;.
 For example:
<verb>echo &lcub;ps output follows:
</verb>
<verb>&rcub; `ps'
</verb>


This prints the string &dquot;ps output follows:&dquot; followed on the
 next line by the current output from the command &dquot;ps&dquot;. That output
 from  &dquot;ps&dquot;  would have its embedded newlines replaced by whitespaces.

<item>COMMAND LINE FILE REDIRECTION: 
<itemize>
<item>Redirection should appear after a command and its arguments in a line to
 be interpreted by husky. A special case is a line that just contains &dquot;&gt;
 filename&dquot; which creates the filename with zero length if it didn't previously
 exist or truncates to zero length if it did. 
<item>Redirection of standard in to come from a file uses the token &dquot;&lt;&dquot;
 with the filename appearing to its right. The default source of standard in
 is the console. 
<item>Redirection of standard out to go to a file uses the token &dquot;&gt;&dquot;
 with the filename appearing to its right. The default destination of standard
 out is the console. 
<item>Redirection of standard error to go to a file uses the token &dquot;&gt;&lsqb;2&rsqb;&dquot;
 with the filename appearing to its right. The default destination of standard
 error is the console. 
<item>Redirection of writes from within a command which uses a known file descriptor
 number (say &dquot;n&dquot;) to go to a file uses the token &dquot;&gt;&lsqb;n&rsqb;&dquot;
 with the filename appearing to its right.
<item>Redirection of read from within a command which uses a known file descriptor
 number (say &dquot;n&dquot;) to come from a file uses the token &dquot;&lt;&lsqb;n&rsqb;&dquot;
 with the filename appearing to its right.
<item>Redirection of reads and writes from within a command which uses a known
 file descriptor number (say &dquot;n&dquot;) to a file uses the token &dquot;&lt;&gt;&lsqb;n&rsqb;&dquot;
 with the filename appearing to its right. In order to redirect both standard
 out and standard error to the one file the form &dquot; &gt; filename &gt;&lsqb;2=1&rsqb;&dquot;
 can be used. This sequence first redirects standard  out  (i.e. file descriptor
 1) to filename and then redirects what is written to file descriptor 2 (i.e.
 standard error) to file descriptor 1 which is now associated with filename.
</itemize>
<item>ENVIRONMENT VARIABLES: Each process can access the name it was invoked
 by via the variable: &dquot;arg0&dquot; . The command line arguments (excluding
 the invocation name) can be accessed as a list in the variable: &dquot;argv&dquot;
 . The number of elements in the list &dquot;argv&dquot; is place in &dquot;argc&dquot;.
 The get command is useful for fetching individual arguments from this list.
 The pid of the current process can be fetched from the variable: &dquot;pid&dquot;.
 When a script launches a new process in the background then the child's pid
 can be accessed from the variable &dquot;child&dquot;. The variable &dquot;ContollerId&dquot;
 is set to the RaidRunner controller number husky is running on. Environment
 variables are a separate &dquot;space&dquot; for each process. Depending on
 the way a process was created, its initial set of environment variables may
 be copied from its parent process at the &dquot;spawn&dquot; point.
<item>SEE ALSO: intro
</itemize>
<sect1>HWCONF - print various hardware configuration details
<p>
<itemize>
<item>SYNOPSIS: hwconf &lsqb;-D&rsqb; &lsqb;-M&rsqb; &lsqb;-I&rsqb; &lsqb;-d
 &lsqb;-n&rsqb;&rsqb; &lsqb;-f&rsqb; &lsqb;-h&rsqb; &lsqb;-i -p c.s.l&rsqb;
 &lsqb;-m&rsqb; &lsqb;-p c.s.l&rsqb; &lsqb;-s&rsqb; &lsqb;-S&rsqb; &lsqb;-t&rsqb;
 &lsqb;-T&rsqb; &lsqb;-P&rsqb; &lsqb;-W&rsqb;
<item>DESCRIPTION: hwconf prints details about the RaidRunner hardware and devices
 attached.
<item>OPTIONS:
<itemize>
<item>-h: Print  the number of controllers, host interfaces per controller, the
 number of disk channels per controller, number of ranks of disks and the details
 memory (in bytes) on each  controller.  Four memory  figures  are printed,
 the first is the total memory in the controller, next is the amount of memory
 at boot time, next is the amount currently available and lastly is the  largest
 available contiguous area of memory.  This is the default option.
<item>-f: Print  the  number  of  fans in the RaidRunner and then the speed for
 each fan in the system. The speeds values are in revolutions per minute (rpms).
 The fans in the system are  labeled  in  your hardware  specification sheet
 for your RaidRunner. The first speed printed from this command corresponds
 to fan number 0 on your specification sheet, the second is for fan 1, and so
 forth.
<item>-d: Print out information on all the disk drives on the RaidRunner.  For
 each disk on the RaidRunner, print out - the  device  name,  in  the format
 c.s.l where c is the channel, s is the SCSI ID (or rank) and l is the SCSI
 LUN of the device, the manufacturer's name (vendor id), the disk's model name
 (product id), the disk's version id, the disk serial number, the disk geometry
 - number of cylinders, heads and sectors, and the last block number on the
 disk and the block size in bytes. the disk revolution count per minute (rpm's),
 the number of notches/zones available on the drive (if any)
<item>-n: Print out the disk drive notch/zone tables if available.  This is a
 sub-option to the -d  option. Not  all  disks appear to correctly report the
 notch/zone partition tables.  For each notch/zone,
<item>the following is printed: the zone number, the zone's starting cylinder,
 the zone's starting head, the zone's ending cylinder, the zone's ending head,
 the zone's starting logical block number, the zone's ending logical block number,
 the zone's number of sectors per track
<item>-D: Print out the device names for all disk drives on the system.
<item>-I: Initialize back-end NCR SCSI chips.  This flag may be used in conjunction
 with any  other  option and  will  done first. It has an effect only the first
 call to hwconf that has not yet used a -d, -D or -I options,  or on those chips
 that have not yet had a -p on the  channel  associated  with that chip.
<item>-m: Print  out  major  flash and battery backed-up ram addresses (in hex).
 Additionally print out the size of the RaidRunner configuration area.  Eight
 (8) addresses are printed in order RaidRunner configuration area start and
 end addresses (FLASH RAM), RaidRunner Husky Scripts area start and end addresses
 (FLASH RAM), RaidRunner Binary Image area start and end addresses (FLASH RAM),
 RaidRunner Battery Backed-up area start and end addresses. And the size of
 the RaidRunner configuration area (in bytes) is then printed.
<item>-p c.s.l: Probe a single device specified by the given channel, SCSI ID
 (rank) and SCSI LUN provided in the format  &dquot;c.s.l&dquot;. The output
 of this command is the same as the &dquot;-d&dquot; option but just for the
 given device. If the device is not present then nothing will be output and
 the exit status of the  command will be 1.
<item>-i -p c.s.l: Re-initialize  the SCSI device driver specified by the given
 channel, SCSI ID (rank) and SCSI LUN provided in the format &dquot;c.s.l&dquot;.
 Typically this command is used when, on a running  RaidRunner,  a new drive
 is plugged in, and it will be used prior to the RaidRunner's next reboot.
<item>-M: Set  the  boottime  memory. This option is executed internally by the
 controller at boot time and has no function (or effect) executed at any other
 time.
<item>-s: Print the 12 character serial number of the RaidRunner.
<item>-S: Issue SCSI spin up commands to all backends as quickly as possible.
 This option is  intended  for use at power-on stage only.
<item>-t: Probe  the  temperature  monitor  returning the internal temperature
 of the RaidRunner in degrees Celsius.
<item>-T: Print the temperatures being recorded by the hardware monitoring daemon
 (hwmon).
<item>-P: For both AC and DC power supplies, print the number of each present
 and the state of each supply. The state will be printed as ok or flt depending
 on whether the PSU is working or faulty.
<item>-W: This  option  will  wait until all possible backends have spun up.
 It is used in conjunction with
</itemize>
<item>NOTES : The order of printing the disk information is by SCSI ID (rank),
 by channel, by SCSI LUN.
</itemize>
<sect1>HWMON - monitoring daemon for temperature, fans, PSUs.
<p>
<itemize>
<item>SYNOPSIS: hwmon &lsqb;-t seconds&rsqb; &lsqb;-d&rsqb;
<item>DESCRIPTION: hwmon  is  a  hardware  monitoring  daemon.  It  periodically
 probes the status of certain elements of a RaidRunner and if an out-of-band
 occurrence happens, will cause the alarm to sound  or  light  up  fault leds
 as well as saving a message in the system log. Depending on the model of RaidRunner,
 the elements monitored are temperature, fans and power supplies. When an out-of-band
 occurrence is found, hwmon will reduce the time between probes to 5 seconds.
 If  a  buzzer is the alarm device, then the buzzer will turn on for 5 seconds
 then off for 5 seconds and repeat this cycle until the buzzer is muted or the
 occurrence is corrected.

If the RaidRunner model supports a buzzer muting switch, then the buzzer
 will be muted if the switch  is pressed  during  a  cycle change as per the
 previous paragraph. When hwmon recognizes the mute switch it will beep twice.


Certain out-of-band occurrences can be considered to be catastrophic, meaning
 if the occurrence  remains uncorrected,  the  RaidRunner's  hardware is likely
 to be damaged. Occurrences such as total fan failure and sustained high temperature
 along with total or partial fan failure are considered  as  catastrophic. hwmon
  has  a  means  of automatically placing the RaidRunner into a &dquot;shutdown&dquot;
 or quiescent state where minimal power is consumed (and hence less heat is
 generated). This is  done  by  the  execution  of  the shutdown command  after
  a period of time where catastrophic out-of-band occurrences are sustained.
 This process is enabled, via the AutoShutdownSecs internal variable. See the
  internals  manual  for use of this variable. hwmon  can  be  prevented from
 starting at boot time by creating the global environment variable NoHwmon and
 setting any value to it. A warning message will be stored in the syslog.
</itemize>
<itemize>
<item>OPTIONS:
<itemize>
<item>t seconds: Specify the number of seconds to wait between probes of the
 hardware elements.  If this option is not specified, the default period is
 300 seconds.
<item>-d: Turn on debugging mode which can produce debugging output.
</itemize>
<item>SEE ALSO: hwconf, pstatus, syslogd, shutdown, internals
</itemize>
<sect1>INTERNALS - Internal variables used by RaidRunner to change dynamics of
 running kernel
<p>
<itemize>
<item>DESCRIPTION: Certain  run-time  features  of the RaidRunner can be manipulated
 by changing internal variables via the setiv command. The table below describes
 each changeable variable, it's effect, it's default value and range of values
 it can be set to. The  variables  below  are  run-time  features  of a RaidRunner
 and hence are always set to their default values when a RaidRunner boots. Certain
 variables can be stored as a global environment variable and will over-ride
 the  defaults  at boot time.  If you create a global environment variable of
 that variable's name with an appropriate value, it's default value will be
 over-ridden the next time the RaidRunner is re-booted. Note, that the values
 of these variables  ARE  NOT CHECKED  when set in the global environment variable
 tables and, if incorrectly set, will generate errors at boot until deleted
 or corrected.  In the table below, any variable that can have a value stored
 as a global  environment  variable is marked with (GEnv)
<item>write_limit: This  variable  is  the  maximum  number of 512-byte blocks
 the cache filesystem will buffer for writes. If this limit is reached all writes
 to the cache filesystem will be blocked until the cache filesystem has  written
  out (to it's backend) enough blocks to reach a low water mark - write_low_tide.
 This  variable  cannot  be  changed if battery backed-up RAM is available as
 it is tied to the amount of battery backed-up RAM available. The value of this
 variable is calculated when the cache is initialized. It's value is dependant
 on whether  battery  backed-up RAM is installed in the RaidRunner. If installed,
 the number of blocks of data that can be saved into the battery backed-up RAM
 is calculated. If no battery backed-up RAM is present, it's value is set  to
  75&percnt; of  the  RaidRunner's  memory  (expressed  in a count of 512 byte
 blocks) then adjusted to reflect the amount of cache requested by configured
 raid sets. When write_limit is changed then both write_high_tide and write_low_tide
  are  automatically  changed  to  there default values (a function of the value
 of write_limit).
<item>write_high_tide: This variable is a high water mark for the number of written-to
 512-byte blocks in the cache. When the number of data blocks exceeds this value,
 to avoid the cache filesystem from blocking it's front end, the  cache  flushing
 mechanism  continually  flushes the cache buffer until the amount of unwritten
 (to the backend) cache buffers is below the low water mark (write_low_tide).
 This value defaults to 75&percnt; of write_limit. This variable can have values
 ranging from write_limit down to write_low_tide. It is recommended that this
 variable not be changed.
<item>write_low_tide: This variable is a low water mark for when the cache flushing
 mechanism is continually  flushing  data  to  it's backend. Once  the  number
  of written-to cache blocks yet to be flushed equals or is less than this value,
 the sustained flushing is stopped. This value defaults to 25&percnt; of write_limit.
 This variable can have values ranging from write_high_tide-1 down to zero (0).
 It is recommended that this variable not be changed.
<item>cache_nflush: This variable is the number of cache buffers (not 512-byte
 data blocks) that the cache flushing  mechanism  will attempt to write out
 in one flush cycle. Adjusting  this  value  may improve performance on writes
 depending of the size of the cache buffers and type of disk drives used in
 the raid set backends. The default value is 128. It's value can range from
 2 to 128.
<item>cache_nread: This variable is the number of cache buffers (not 512-byte
 data blocks) that the cache  reading  mechanism  will attempt to read out in
 one read cycle. Adjusting  this  value  may  improve performance on reads depending
 of the size of the cache buffers and type of disk drives used in the raid set
 backends. The default value is 128. It's value can range from 2 to 128.
<item>cache_wlimit: This variable is the number of cache buffers (not 512-byte
 data blocks) that the cache flushing  mechanism  will attempt  coalesce  into
  a  single sequential write. It is different to cache_nflush in that cache_nflush
 is the total number of cache buffers that can be written in a single cache
 flush cycle and these buffers  can  be  non sequential  whereas  cache_wlimit
 is a limit on the number of sequential cache buffer's that can be written with
 one write. Adjusting this value may improve performance on writes depending
 of the size of the cache buffers  and  type  of disk drives used in the raid
 set backends. The default value is 128. It's value can range from 2 to 128.
<item>cache_fperiod (GEnv): By  default, the cache flushes any data to be written
 every 1000 milliseconds (unless it's forced to by the fact that the cache is
 getting full and then it flushes the cache and resets the timer).  You can
 vary this  flushing period  by setting this variable.  Given you have a large
 number of sustained reads and minimal writes, then you may want to delay the
 writes out of cache to the backends as long as possible. Note, that by setting
 this  to  a high value, you run the risk of loosing what you have written.
 The default value is 1000 milliseconds (i.e 1 second). It's value can range
 from 500ms to 300000ms.
<item>scsi_write_thru (GEnv): By  default all writes (from a host) are buffered
 in the RaidRunner's cache and are flushed to the backend disks periodically.
 When battery backed-up RAM is available then this results in the most efficient
 write  throughput. If no battery backed-up RAM is available or you do not want
 to depend on writes being saved in battery backed-up RAM in event of a power
 failure you can force the RaidRunner to write data straight thru to the  backends
  prior to returning an OK status to the host. This essentially provides a write-thru
 cache. The default value of this variable is 0 - write-thru mode is DISABLED.
 The values this variable can take are
<itemize>
<item>0 - DISABLE write-thru mode, or
<item>1 - ENABLE write-thru mode.
</itemize>
<item>scsi_write_fua (GEnv): This variable effects what is done when the FUA
 (Force Unit Access) bit is set on a SCSI WRITE-10 command. When  this  variable
  is  enabled  and a SCSI WRITE-10 command has the FUA bit set is processed
 then the data is written directly thru the cache to the backend disks. If the
 variable is disabled, then the setting of  the  FUA bit on SCSI WRITE-10 commands
 is ignored. The  default value for this variable is disabled (0) if battery
 backed-up RAM is present, or enabled (1) if battery backed-up RAM is NOT present.
 The values this variable can take are
<itemize>
<item>0 - IGNORE FUA bit on SCSI WRITE-10 commands, or
<item>1 - ACT on FUA bit on SCSI WRITE-10 commands.
</itemize>
<item>scsi_ierror (GEnv): This variable controls what is done when the RaidRunner
 receives a Initiator Detected Error message  on  a  SCSI host channel. If 
 set  (1), cause an Check Condition, If NOT set (0), follow the SCSI-2 standard
 and re-transmit the Data In / Out phase. The default value is 0. The values
 this variable can take are
<itemize>
<item>0 - follow SCSI-2 standard
<item>1 - ignore the SCSI-2 standard and cause a Check Condition.
</itemize>
<item>scsi_sol_reboot (GEnv): Determines whether to auto-detect a Solaris reboot
 and the clear any wide mode negotiations. If set (1), detect a Solaris reboot
 and clear wide mode.  If NOT set (0), follow the  SCSI-2  standard  and  not
 clear wide mode. The default value is 0. The values this variable can take
 are
<itemize>
<item>0 - follow SCSI-2 standard
<item>1 - ignore the SCSI-2 standard and clear wide mode.
</itemize>
<item>scsi_hreset (GEnv): Determines whether to issue a SCSI bus reset on host
 ports after power-on. If  set  (1), then a SCSI bus reset is done on the host
 port when starting the first smon/stargd process on that port.  If NOT set
 (0), nothing is done. The default value is 0. The values this variable can
 take are
<itemize>
<item>0 - don't issue SCSI bus resets on power-on.
<item>1 - issue SCSI bus resets on power-on when the first smon/stargd process
 is started.
</itemize>
<item>scsi_full_log (GEnv): Determines whether or not stargd reports, via syslog,
 a Reset Check condition on Read, Write,  Test  Unit  Ready and Start Stop commands.
 This reset check condition is always set when a RaidRunner boots or the raid
 detects a scsi-bus reset. Note that this variable only suppresses the logging
 of this Check condition into syslog, it does not effect the response to the
 host of this and any Check condition. If  set  (1),  then  all stargd detected
 reset Check condition error messages are logged.  If NOT set (0), these messages
 are suppressed The default value is 0. The values this variable can take are
<itemize>
<item>0 - suppress logging these messages
<item>1 - log all messages.
</itemize>
<item>scsi_ms_badpage (GEnv): Determines whether or not stargd reports, via syslog,
 that it has received a non-supported page number in a MODE SENSE  or  MODE
 SELECT command it receives from a host. Note that stargd will issue the appropriate
 Check condition to the host (&dquot;Invalid Field in CDB&dquot;) irrespective
 of the value of this variable. If set (1), then all stargd detected non-supported
 page numbers in MODE SENSE and MODE SELECT commands  will  be   logged.  If
 NOT set (0), these messages are suppressed The default value is 0. The values
 this variable can take are
<itemize>
<item>0 - suppress logging these messages
<item>1 - log all messages.
</itemize>
<item>scsi_bechng (GEnv): Determines  whether  or not the raid reports backend
 device parameter change errors. In a multi controller environment, backends
 are probed and some of their parameters are changed by a booting controller.
 This will  generate parameter change mode sense errors. If cleared (0), then
 all parameter change errors will NOT be logged.  If set (1), these messages
 are logged like any other backend error. The default value is 0. The values
 this variable can take are
<itemize>
<item>0 - suppress logging these messages
<item>1 - log all messages.
</itemize>
<item>scsi_dnotch (GEnv): Some disk drives take an inordinate amount of time
 to perform mode select commands.  One  set  of  information  a RaidRunner 
 will  obtain from a device backend are the disk notch pages (if present). As
 this is for information only, then to reduce the boot time of a RaidRunner
 you can request that disk notches are not obtained. If cleared (0), backend
 disk notch information is not probed for.  If set (1), then backend disk notch
  information is probed for. The default value is 1. The values this variable
 can take are:
<itemize>
<item>0 - don't probe for notch pages
<item>1 - probe for notch pages
</itemize>
<item>scsi_rw_retries (GEnv): Specify  the  number  of  read  or write retries
 to perform on a device backend before effecting an error on the given operation.
 Note that ALL retries are reported via syslog. The default value is 3. It's
 value can range from 1 to 9.
<item>scsi_errpage_r (GEnv): Specify the number of internal read retries that
 a disk backend is to perform before reporting an error (to  the raid). Setting
 this variable causes the Read Retry Count field in the Read-Write Error Recovery
 mode sense page. A value of -1 will cause the drive's default to be used. The
 default value is -1. It's value can range from -1 (use disk's default) or from
 0 to 255.
<item>scsi_errpage_w (GEnv): Specify the number of internal write retries that
 a disk backend is to perform before reporting an error (to the raid).  Setting
  this  variable  causes  the Write Retry Count field in the Read-Write Error
 Recovery mode sense page.  A value of -1 will cause the drive's default to
 be used. The default value is -1. It's value can range from -1 (use disk's
 default) or from 0 to 255.
<item>BackFrank: Specify the SCSI-ID of the first rank of backend disks on a
 RaidRunner.  This variable should never  be  changed and is for informative
 purposes only. The default value is dependant on the model of RaidRunner being
 run. The values this variable can take are
<itemize>
<item>0 - the first rank SCSI-ID will be 0
<item>1 - the first rank SCSI-ID will be 1
</itemize>
<item>raid_drainwait (GEnv): Specify  the  number  of  milliseconds  a  raidset
 is to delay, before draining all backend I/O's when a backend fails. Setting
 this variable to a lower value will speed up the commencement of any  error
  recovery  procedures that would be performed on a raid set when a backend
 fails. The default value is 500 milliseconds. It's value can range from 50
 to 10000 milliseconds.
<item>EnclosureType: Specify  the  enclosure  type a raid controller is running
 within.  This variable should never be changed and is for informative purposes
 only. The default value is dependant on the model of RaidRunner being run.
 The values this variable can take are integers starting from 0.
<item>fmt_idisc_tmo (GEnv): Specify the SCSI command timeout (in milliseconds)
 when a SCSI FORMAT command  is  issued  on  a  backend.  Disk drives take different
 amounts of time to perform a SCSI FORMAT command and hence a timeout is required
 to be set when the command is issued. As certain drives may take longer to
 format than the default timeout you can  change it. The default value is 720000
 milliseconds. It's value can range from 200000 to 1440000 milliseconds.
<item>AutoShutdownSecs (GEnv): Specify  the  number  of seconds the RaidRunner
 should monitor catastrophic hardware failures before deciding to automatically
 shutdown. A catastrophic failure is one which will cause damage to the  RaidRunner's
  hardware  if not  fixed  immediately.  Failures  like all fans failing would
 be considered catastrophic. A value of 0 seconds (the default) will disable
 this feature, that is, with the exception of  logging  the  errors,  no  action
  will occur.  See the shutdown and hwmon for further details. The default value
 is 0 seconds. It's value can range from 20 to 125 seconds.
<item>SEE ALSO: setiv, getiv, syslog, setenv, printenv, hwmon, shutdown
</itemize>
<sect1>KILL - send a signal to the nominated process
<p>
<itemize>
<item>SYNOPSIS: kill &lsqb;-sig_name&rsqb; pid
<item>DESCRIPTION: kill sends a signal to the process nominated by pid. If the
 pid is a positive number then only the nominated process is signaled. If the
 pid is a negative number then the signal is sent to all processes in the same
 process group as the process with the id of -pid. The switch is optional and
 if not given a SIGTERM (software termination signal) is sent. If the sig_name
 switch is given then it should be one of the following (lower case) abbreviations.
 Only the first 3 letters need to be given for the signal name to be recognized.
 Following each abbreviation is a brief explanation and the signal number in
 brackets:

<itemize>
<item>null - unused signal &lsqb;0&rsqb;
<item>hup - hangup &lsqb;1&rsqb;
<item>int - interrupt (rubout) &lsqb;2&rsqb;
<item>quit - quit (ASCII FS) &lsqb;3&rsqb;
<item>kill - kill (cannot be caught or ignored) &lsqb;4&rsqb;
<item>pipe - write on a pipe with no one to read it &lsqb;5&rsqb;
<item>alrm - alarm clock &lsqb;6&rsqb;
<item>term - software termination signal &lsqb;7&rsqb;
<item>cld - child process has changed state &lsqb;8&rsqb;
<item>nomem - could not obtain memory (from heap) &lsqb;9&rsqb;
</itemize>

You cannot kill processes whose process id is between 0 and 5 inclusive.
 These are considered sacrosanct - hyena, init and console  reader/writers.
</itemize>
<itemize>
<item>SEE ALSO: K9kill
</itemize>
<sect1>LED- turn on/off LED's on RaidRunner
<p>
<itemize>
<item>SYNOPSIS: 
<itemize>
<item>led
<item>led led_id led_function
</itemize>
<item>DESCRIPTION: led uses the given led_id to identify the LED to manipulate
 based on the led_function. When no arguments are given, an internal LED register
 is printed along with the current function the onboard LEDS, led1 and led2
 are tracing. If a undefined led_id is given, the led command silently does
 nothing and returns NULL. If an incorrect number of arguments or invalid led_function
 is given a usage message is printed. Depending on the RaidRunner model the
 led_id can be one of
<itemize>
<item>led1 - LED1 on the RaidRunner controller itself
<item>led2 - LED2 on the RaidRunner controller itself
<item>Dc.s.l - Device on channel c, scsi id s, scsi lun l
<item>status - the status LED on the RaidRunner
<item>io - the io LED on the RaidRunner
</itemize>

and led_function can be one of
<itemize>
<item>on - turn on the given LED
<item>off - turn off the given LED
<item>ok - set the given LED to the defined OK state
<item>faulty - set the given LED to the defined FAULTY state
<item>warning - set the given LED to the defined WARNING state
<item>rebuild - set the given LED to the defined REBUILD state
<item>tprocsw - set the given LED to trace kernel process switching
<item>tparity - set the given LED to trace I/O parity generation
<item>tdisconn - set the given LED to trace host interface disconnect activity
<item>pid - set the given LED to trace the process pid as it runs
</itemize>

Different models of RaidRunner have various differences in number of LED's
 and their functionality.  Depending on the type of LED, the ok, faulty, warning
 and rebuild functions perform different functions. See your RaidRunner's Hardware
 Reference manual to see what LED's exist and what different functions do.

<item>NOTES: Tracing activities can only occur on the `onboard` leds (LED1, LED2).
<item>SEE ALSO: lflash
</itemize>
<sect1>LFLASH- flash a led on RaidRunner
<p>
<itemize>
<item>SYNOPSIS: lflash led_id period
<item>DESCRIPTION: lflash uses the given led_id to identify the LED to flash
 every period seconds. If a undefined led_id is given, the led command silently
 does nothing and returns NULL. Depending on the RaidRunner model the led_id
 can be one of:

<itemize>
<item>led1 - LED1 on the RaidRunner controller itself
<item>led2 - LED2 on the RaidRunner controller itself
<item>Dc.s.l - Device on channel c, scsi id s, scsi lun l 
<item>status - the status LED on the RaidRunner
<item>io - the io LED on the RaidRunner
</itemize>

<item>NOTE: The number of seconds must be greater than or equal to 2.
<item>SEE ALSO: led
</itemize>
<sect1>LINE - copies one line of standard input to standard output
<p>
<itemize>
<item>SYNOPSIS: line
<item>DESCRIPTION: line accomplishes the one line copy by reading up to a newline
 character followed by a single K9write.
<item>SEE ALSO: K9read, K9write
</itemize>
<sect1>LLENGTH - return the number of elements in the given list
<p>
<itemize>
<item>SYNOPSIS: llength list
<item>DESCRIPTION: llength returns the number of elements in a given list.
<item>EXAMPLES: Some simple examples:<tscreen>
<verb>set list D1 D2 D3 D4 D5 &num; create the list
</verb></tscreen>
<verb>set len `llength &dollar;list' &num; get it's length
</verb>
<verb>echo &dollar;len
</verb>
<verb>5
</verb>
<verb>set list &lcub;D1 D2 D3 D4 D5&rcub; &lcub;D6 D7&rcub;  &num; create the
 list
</verb>
<verb>set len `llength &dollar;list' &num; get it's length
</verb>
<verb>echo &dollar;len
</verb>
<verb>2
</verb>
<verb>set list &lcub;&rcub; &num; create an empty list
</verb>
<verb>set len `llength &dollar;list' &num; get it's length
</verb>
<verb>echo &dollar;len
</verb>
<verb>0
</verb>
</itemize>
<sect1>LOG - like zero with additional logging of accesses
<p>
<itemize>
<item>SYNOPSIS: bind -k &lcub;log fd error_rate tag&rcub; bind_point
<item>DESCRIPTION: log is a special  file that when written to is a infinite
 sink of data (i.e. anything can be written to it and it will be disposed of
 quickly). When log is read it is an infinite source of zeros (i.e. the byte
 value 0). The log file will appear in the K9 namespace at the bind_point. Additionally,
  ASCII  log  data  is  written  to  the file associated with file descriptor
 fd. error_rate should be a number between 0 and 100 and is the percentages
 of errors (randomly distributed) that will be reported (as an  EIO  error)
  to  the caller. Each line written to fd will have tag appended to it. There
 is one line output to fd for each IO operation on the log special file. The
 first character output is &dquot;R&dquot; or &dquot;W&dquot; indicating a read
 or write. The second character is blank if no error was reported and &dquot;*&dquot;
 if one was reported.  Next  (after  a white  space)  is  a (64 bit integer)
 offset into the file of the start of the operation, followed by the size (in
 bytes) of that operation. The line finishes with the tag.
<item>EXAMPLE: Bind a log special file at &dquot;/dev/log&dquot; that writes
 log information to standard error. Each line written to standard error has
 the tag string &dquot;scsi&dquot; appended to it.  Approximately 30&percnt;
 of reads and writes (i.e. randomly distributed) return an EIO error to the
 caller. This is done as follows:<tscreen>
<verb>bind &dquot;log 2 30 scsi&dquot; /dev/log
</verb></tscreen>
<verb>dd if=/dev/zero of=/dev/log count=5 bs=512
</verb>
<verb>W  0000000000 512        scsi
</verb>
<verb>W  0000000200 512        scsi
</verb>
<verb>W  0000000400 512        scsi
</verb>
<verb>W* 0000000600 512        scsi
</verb>
<verb>Write failed.
</verb>
<verb>4+0 records in
</verb>
<verb>3+0 records out
</verb>

<item>SEE ALSO: zero
</itemize>
<sect1>LRANGE - extract a range of elements from the given list
<p>
<itemize>
<item>SYNOPSIS: lrange first last list
<item>DESCRIPTION: lrange returns a list consisting of elements first through
 last of list. 0 refers to the first element in the list. If first is greateR
 THAN last then the list is extracted in reverse order.
<item>EXAMPLES: Some simple examples:
<verb>set list D1 D2 D3 D4 D5 &num; create the list
</verb>
<verb>set subl `lrange 0 3 &dollar;list' &num; extract from indices 0 to 3
</verb>
<verb>echo &dollar;subl
</verb>
<verb>D1 D2 D3 D4
</verb>
<verb>set subl `lrange 3 1 &dollar;list' &num; extract from indices 3 to 1
</verb>
<verb>echo &dollar;subl
</verb>
<verb>D4 D3 D2
</verb>
<verb>set subl `lrange 4 4 &dollar;list' &num; extract from indices 0 to 3
</verb>
<verb>echo &dollar;subl &num; equivalent to get 4 &dollar;list
</verb>
<verb>D5
</verb>
<verb>set subl `lrange 3 100 &dollar;list'
</verb>
<verb>echo &dollar;subl
</verb>
<verb>D4 D5
</verb>
</itemize>
<sect1>LS - list the files in a directory
<p>
<itemize>
<item>SYNOPSIS: ls &lsqb; -l &rsqb; &lsqb; directory... &rsqb;
<item>DESCRIPTION: ls lists the files in the given directory on standard out.
 If no directory is given then the root directory (i.e. &dquot;/&dquot;) is
 listed. Each file name contained in a directory is put on a separate line.
 Each listing has a lead-in line stating which directory is being shown. If
 there  is  more than one directory then they are listed sequentially separated
 by a blank line. If the &dquot;-l&dquot; switch is given then every listed
 file has data such as its length and the file system it belongs to shown on
 the same line as its name. See the stat command for more information. ls is
 not an inbuilt command but a husky script which utilizes cat and stat. The
 script source can be found in the file &dquot;/bin/ps&dquot;.
<item>SEE ALSO: cat, stat 
</itemize>
<sect1>LSEARCH - find the a pattern in a list 
<p>
<itemize>
<item>SYNOPSIS: lsearch pattern list
<item>DESCRIPTION: lsearch returns the index of the first element in list that
 matches pattern or -1 if none. 0 refers to the first element in the list
<item>EXAMPLES: Some simple examples:
<verb>set list D1 D2 D3 D4 D5 &num; create the list
</verb>
<verb>set idx `lsearch D4 &dollar;list' &num; get index of D4 in list
</verb>
<verb>echo &dollar;idx
</verb>
<verb>3
</verb>
<verb>set idx `lsearch D1 &dollar;list' &num; get index of D1 in list
</verb>
<verb>echo &dollar;idx
</verb>
<verb>0
</verb>
<verb>set idx `lsearch D8 &dollar;list' &num; get index of D8 in list
</verb>
<verb>echo &dollar;idx &num; equivalent to get 4 &dollar;list
</verb>
<verb>-1
</verb>
</itemize>
<sect1>LSUBSTR - replace a character in all elements of a list
<p>
<itemize>
<item>SYNOPSIS: lsubstr find_char replacement_char list
<item>DESCRIPTION: lsubstr returns a list replacing every find_ch character found
 in any element of the list with the replacement_char character. replacement_char
 can be NULL  which  effectively deletes all find_char characters in the list.
<item>EXAMPLES: Some simple examples:
<verb>set list D1 D2 D3 D4 D5 &num; create the list
</verb>
<verb>set subl `lsubstr D x &dollar;list' &num; replace all D's with x's
</verb>
<verb>echo &dollar;subl
</verb>
<verb>x1 x2 x3 x4 x5
</verb>
<verb>set subl `lsubstr D &lcub;&rcub; &dollar;list' &num; delete all D's
</verb>
<verb>echo &dollar;subl
</verb>
<verb>1 2 3 4 5
</verb>
<verb>set list -L -16 &num; create a list with embedded braces
</verb>
<verb>set subl `lsubstr &lcub;&rcub; &dollar;list' &num; delete all open braces
</verb>
<verb>set subl `lsubstr &lcub;&rcub; &dollar;subl' &num; delete all close braces
</verb>
<verb>echo &dollar;subl
</verb>
<verb>-L 16
</verb>
</itemize>
<sect1>MEM - memory mapped file (system)
<p>
<itemize>
<item>SYNOPSIS: bind -k &lcub;mem first last &lsqb; r &rsqb;&rcub; bind_point
<item>DESCRIPTION: mem  allows  machine memory to be accessed as a single K9
 file (rather than a file system). The host system's memory is used starting
 at the first memory location up to and including the last memory location.
 Both first and last need to be given  in hexadecimal. If successful the mem
 file will appear in the K9 namespace at the bind_point. The stat command will
 show it as a normal file with the appropriate size (i.e. last - first + 1).
 If the optional &dquot;r&dquot; is given then only read-only access to the
 file is permitted. In a target environment mem can usefully associate battery
 backed-up RAM (or ROM) with the K9 namespace. In a Unix  environment  it  is
  of  limited  use (see unixfd instead). In a DOS environment it may be useful
 to access memory directly (IO space) but for accessing the DOS console see
 doscon. When mem is associated with the partition of Flash RAM that stores
 the husky scripts, which is  stored  compressed, reading from that page will
 automatically decompress and return the data as it is read. When  mem  is associated
 with the writable partitions of Flash RAM (configuration partition, husky script
 partition and main binary partition) a write to the start of any partition
 will erase that partition.
<item>SEE ALSO: ram
<item>BUGS: Only a single file rather than a file system can be bound.
</itemize>
<sect1>MDEBUG - exercise and display statistics about memory allocation
<p>
<itemize>
<item>SYNOPSIS: mdebug &lsqb;off|on|trace|p|m size|f ptr|c nel elsize|r ptr size&rsqb;
<item>DESCRIPTION: mdebug  can  be  used to directly allocate and free memory.
  mdebug will also print (to standard output) information about the current
 state of memory allocation.  With out any given options a brief five  line
 summary of memory usage is printed, e.g.<tscreen>
<verb>: raid; mdebug
</verb></tscreen>
<verb>Mdebug is off
</verb>
<verb>nreq-nfree=87096-82951=4145(13905745)
</verb>
<verb>size=15956672/16150000
</verb>
<verb>waste=1&percnt;/2&percnt;
</verb>
<verb>list=4251/8396
</verb>
<verb>: raid;
</verb>


The first line indicates the debug mode,  either off, on or trace.  The
 second line indicates the number times a request for memory is made (to Mmalloc()
 or Mcalloc() and related functions) and the  number  of times  the  memory
 allocator is called to free memory (via Mfree()).  The difference between these
 first two numbers is the total number of currently allocated blocks of memory,
  with the  number  between  the '('  and  ')'  being  the total memory requested.
  Note that the amount of memory actually assign may be more than requested.


The third line indicates the amount of memory being managed.  The second
 number is the total memory man aged (i.e. left over after loading the statically
 allocated text, data and bss space).  The first number is that left over after
 various memory allocation tables have been subtracted out from that  afore
  mention  number.  The fourth line is the total amount of extra memory assigned
 to requests in excess of the actual requested memory as compared with the totals
 on line 3.


The fifth line relates to the list of currently allocated memory.  The
 first number  is  the  number  of free entries left and the second is the maximum
 table size.  Note that the number of currently allocated blocks (third number
 on line 2) when added to the first number on line 5 gives the second number
 on line 5.

<item>OPTIONS:
<itemize>
<item>p: Prints the above mentioned five line summary and then the free list.
<item>P: Prints all the above plus dumps the list of currently allocated memory.
<item>PP: Prints all the above plus the free bitmap.
</itemize>

The  above  three  options can generate copious output and require a detailed
 knowledge of the source to understand their meaning.
<itemize>
<item>off: Turns off memory allocation debugging.  This is the default condition
 after booting.
<item>on: Turns on memory allocation assertion checking.
<item>trace: Turns on memory allocation assertion checking and traces every memory
 allocation /  deallocation.
<item>m: Uses Mmalloc() to allocate a block of memory of size bytes.
<item>f: Uses Mfree() to de-allocate a block of memory addressed by ptr.
<item>c: Uses  Mcalloc()  to allocate a contiguous block of memory consisting
 of nel elements each of size bytes.
<item>r: Uses Mrealloc() to re-allocate a block of previously allocated memory,
 ptr,  changing  the  allocated size to be size bytes.
</itemize>
<item>SEE ALSO: Unix man pages on malloc()
</itemize>

<sect1>MKDIR - create directory (or directories)
<p>
<itemize>
<item>SYNOPSIS: mkdir &lsqb; directory_name ... &rsqb;
<item>DESCRIPTION: mkdir creates the given directory (or directories). If all
 the given directories can be created then NIL is returned as the status; otherwise
 the first directory that could not be created is returned (and this command
 will continue trying to create directories until the list is exhausted). A
 directory cannot be created with a file name that previously existed in the
 enclosing directory.
</itemize>
<sect1>MKDISKFS - script to create a disk filesystem
<p>
<itemize>
<item>SYNOPSIS: mkdiskfs disk_directory_root disk_name
<item>DESCRIPTION: mkdiskfs  is  a  husky  script which is used to perform all
 the necessary commands to create a disk filesystem given the root of the disk
 file system and the name of the disk.
<item>OPTIONS : 
<itemize>
<item>disk_directory_root: Specify the directory root under which the disk filesystems
 are bound.  This is typically /dev/hd.
<item>disk_name: Specify the name of the disk in the format Dc.s.l where c is
 the channel, s is the scsi  id  (or  rank) and l is the scsi lun of the disk.
</itemize>

After parsing it's arguments mkdiskfs creates the disk filesystem's bind
 point and binds in the disk at that point. set.

<item>SEE ALSO: rconf, scsihdfs
</itemize>
<sect1>MKHOSTFS - script to create a host port filesystem
<p>
<itemize>
<item>SYNOPSIS: mkhostfs controller_number host_port host_bus_directory
<item>DESCRIPTION: mkhostfs  is a husky script which is used to perform all the
 necessary commands to create a host port filesystem on the given RaidRunner
 controller given the root of the host port file systems and the host port 
 number.
<item>OPTIONS:
<itemize>
<item>controller_number: Specify the controller on which the host port filesystem
 is to be created.
<item>host_port: Specify the host port number to create the filesystem for.
<item>host_bus_directory: Specify the directory root under which host filesystems
 are bound. This is typically /dev/hostbus. After  parsing  it's  arguments
 mkhostfs finds out what SCSI ID the host port is to present (see hconf and
 then binds in the host filesystem. set.
</itemize>
<item>SEE ALSO: hconf, scsihpfs
</itemize>

<sect1>MKRAID - script to create a raid given a line of output of rconf
<p>
<itemize>
<item>SYNOPSIS: mkraid `rconf -list RaidSetName'
<item>DESCRIPTION: mkraid  is a husky script which is used to perform all the
 necessary commands to create and enable host access to a given Raid Set. The
 arguments to mkraid is a line of output from a rconf -list  command. After
 parsing  it's  arguments mkraid  checks  to  see if a reconstruction was being
 performed when the RaidRunner was last operating, and if so, notes this.  It
 then creates the raid filesystem (see mkraidfs) and adds a cache frontend to
 the  raid filesystem.  It then creates the required host filesystems (see mkhsotfs)
 and finally, if a reconstruction had been taking place when the RaidRunner
 was last operating, it restarts a reconstruction.
<item>NOTE: This husky script DOES NOT enable target access (stargd) to the raid
 set it creates.
<item>SEE ALSO: rconf, mkraidfs, mkhostfs
</itemize>
<sect1>MKRAIDFS - script to create a raid filesystem
<p>
<itemize>
<item>SYNOPSIS: mkraidfs -r raidtype -n raidname -b backends &lsqb;-c chunk&rsqb;
 &lsqb;-i iomode&rsqb; &lsqb;-q qlen&rsqb; &lsqb;-v&rsqb; &lsqb;-C capacity&rsqb;
 &lsqb;-S&rsqb;
<item>DESCRIPTION: mkraidfs is a husky script which is used to perform all the
 necessary commands to create a Raid filesystem.
<item>OPTIONS: 
<itemize>
<item>-r raidtype: Specify the raid type as raidtype for the raid set. Must be
 0, 1, 3 or 5.
<item>-n raidname: Specify the name of the raid set as raidname.
<item>-b backends: Specify the comma separated list of the raid set's backends
 in the format used by rconf.
<item>-c iosize: Optionally specify the IOSIZE (in bytes) of the raid set.
<item>-i iomode: Optionally specify the raid set's iomode - read-write, read-only,
 write-only.
<item>-q qlen: Optionally specify the raid set's queue length for each backend.
<item>-v: Enable verbose mode which prints out the main actions (binding, engage
 commands) as they are performed.
<item>-C capacity: Optionally specify the raid set's size in 512-byte blocks.
<item>-S: Optionally specify that spares pool access is required should a backend
 fail.
</itemize>

After parsing it's arguments mkraidfs creates the Raid Set's backend filesystems,
 typically, disks  (see  mkdisfs)  taking care of failed backends.  It then
 binds in the raid filesystem and engages the backends into the filesystem.
  If spares access is requested, it enables the autorepair feature of the raid
 set.

<item>SEE ALSO: rconf, mkraidfs, mkhostfs, mkdiskfs, raid&lsqb;0135&rsqb;fs
</itemize>


<sect1>MKSMON - script to start the scsi monitor daemon smon
<p>
<itemize>
<item>SYNOPSIS: mksmon controllerno hostport scsi_lun protocol_list
<item>DESCRIPTION: mksmon  is a husky script which is used to perform all the
 necessary commands to start the scsi monitor daemon smon given the controller
 number, hostport, scsi lun, and the block protocol list. Typically, mksmon,
 is run with it's arguments from the output of a mconf -list command.
<item>OPTIONS:
<itemize>
<item>controllerno: Specify the controller on which the scsi monitor daemon is
 to be run.
<item>hostport: Specify the host port through which the scsi monitor daemon communicates.
<item>scsi_lun: Specify the SCSI LUN the scsi monitor daemon is to respond to.
<item>protocol_list: Specify the comma separated block protocol list the scsi
 monitor daemon is to implement.
</itemize>

After parsing it's arguments mksmon checks to see if it's already running
 and  issues  a  message  if  so  and exits. Otherwise, it creates the host
 filesystem (mkhostfs), creates a memory file and set of fifo's for smon to
 use and finally starts smon set.

<item>SEE ALSO: smon, mconf, mkhostfs, fifofs
</itemize>
<sect1>MKSTARGD - script to initialize a scsi target daemon for a given raid set
<p>
<itemize>
<item>SYNOPSIS: mkstargd `rconf -list raidname'
<item>DESCRIPTION: mkstargd  is  a  husky  script which is used to perform all
 the necessary commands to start and initialize the scsi target daemon stargd
 for a given raid set. Typically, mkstargd, is run with it's arguments from
 the output of a rconf -list command. After parsing it's arguments mkstargd
 checks to see if it's already running and issues a  message  if  so  and exits.
 Otherwise, it creates the host filesystem  (mkhostfs),  then  starts  the scsi
 target daemon (stargd) for the given raid set. stargd is started in a mode
 that responds to non-medium  access  SCSI commands and sets a state of &dquot;spinning
 up&dquot;. Typically  stargd's are started as soon as possible but do not allow
 medium access commands until the underlying raid sets have been created and
 then are flagged as &dquot;spun up&dquot; (via mstargd -o  command)  which
  allows medium access.
<item>SEE ALSO: stargd, rconf, mkhostfs
</itemize>
<sect1>MSTARGD - monitor for stargd 
<p>
<itemize>
<item>SYNOPSIS: mstargd &lsqb;-a&rsqb; &lsqb;-d level&rsqb; &lsqb;-h&rsqb; &lsqb;-hr&rsqb;
 &lsqb;-hw&rsqb; &lsqb;-l&rsqb; &lsqb;-m&rsqb; &lsqb;-n&rsqb; &lsqb;-o offset&rsqb;
 &lsqb;-R&rsqb; &lsqb;-s&rsqb; &lsqb;-t&rsqb; &lsqb;-v&rsqb; &lsqb;-W&rsqb;
 &lsqb;-z&rsqb; &lsqb;-Z spinstate&rsqb; &lsqb;-U&rsqb; &lsqb;-irgap nblks&rsqb;
 pid
<item>DESCRIPTION: mstargd modifies the state or prints out information about
 the stargd daemon with the given pid. If such a process exists and no optional
 switches  are given then the current debug level of that stargd daemon is printed
 to standard out by this call. 

mstargd  works by looking for file named &dquot;/mon/stargd/pid&dquot;.
 If it is not found or the pid does not represent an existing process  then
  mstargd exits with an appropriate error message. If it is found then it is
 assumed to contain a reference into the associated stargd process's state (and
 statistics) structure. The &dquot;reference&dquot; for target hardware such
 as the raid (without memory management) is a memory address. The &dquot;reference&dquot;
 for Unix machines could be a shared memory identifier or a memory address (depending
 on how K9 processes are mapped to Unix processes). 

mstargd performs its monitoring
 (or modifying) task then exits immediately. A sanity check is performed on
 the associated stargd process's state (and statistics) structure before it
 is used. Operations that take a little time (e.g. &dquot;-h&dquot;, &dquot;-s&dquot;
 and &dquot;-t&dquot;) take an internal copy of this state structure. mstargd
 is designed to have no detrimental effect on a running stargd daemon. Note
 that the 3 modifying operations (i.e. &dquot;-o&dquot;, &dquot;-d&dquot; and
 &dquot;-z&dquot;) have no adverse effect either.
<item>OPTIONS
<itemize>
<item>-a: This option has the same effect as giving mstargd the options, &dquot;-h
 -l -m -s -t&dquot;.
<item>-d level: This option will change the debug level of the nominated stargd
 daemon to the given level. The debug levels are:
<itemize>
<item>0 = no debug messages
<item>1 = debug messages on all non-read/write commands
<item>2 = debug messages on all commands
</itemize>
<item>-h: This option will output a histogram for reads and a  separate  one
 for writes. The histogram currently consists of a header line followed by multiple
 lines.  Each line has the number  of  blocks  in its  1st  column,  the number
 of invocations in the 2nd column and the cumulative time in the SCSI data 
 phase  in  the  3rd  column. Only  lines with non-zero invocations are output.
 Block number 257 (if present) will be  the  last  line  and  records  all 
 commands requesting 257 or more blocks.
<item>-hr: This option only prints out the histogram for reads.
<item>-hw: This option only prints out the histogram for writes.
<item>-l: This option prints out the stargd read lookahead statistics.
<item>-m: This option prints out the moniker (i.e name) of the raid set indicated
 by the given pid.
<item>-n: This option toggles the collection of statistics by the  indicated
 stargd process.
<item>-o offset: This  option  informs  the  daemon that reads and writes into
 it's store are to be offset by the given number of blocks. The  default value
  for offset is 0. The given offset must be in the range 0 to (2**32 - 1). The
 typical block size is  512  bytes.   To  simplify writing  out  large numbers
 certain suffixes can be used, see suffix. Additionally, this option informs
 the daemon that  it's  store  is now available for access by setting it's spin
 state to 1. See &dquot;-Z&dquot; option below.
<item>-R: This option sets the write-protect flag which will result  in  any
 write  command  issued  to the stargd process (as indicated by the given pid)
 to return a check condition with the sense key  set  to &dquot;DATA  PROTECT&dquot;
  and  the  additional sense key set to &dquot;WRITE PROTECT&dquot;.
<item>-s: This option prints the current state of  the  SCSI  command  state
 machine.
<item>-t: This  option  prints  a  row each for read(6), read(10), write(6),
 write(10) and others.  These 5 rows represent a categorization  of all  incoming
 SCSI commands. Each row contains the number of invocations and the number of
 errors detected. Errors are divided into 2  categories: type 1 for situations
 when a &dquot;Check Condition&dquot; status is returned, and type 2  when 
 some  other  failed  status  is returned (e.g. &dquot;Command terminated&dquot;
 or &dquot;Reservation conflict&dquot;).
<item>-v: This  option prints out the histogram (-h, -hw, -hr) and SCSI command<6E>
 summary (-t) in vector (or line) form.
<item>-U: This option clears any SCSI-2 reservations set on the scsi  target
 specified  by  the  given  pid. WARNING this clearance &dquot;controller system
 wide&dquot;.
<item>-W: This option clears the write-protect flag which enables write commands
 issued to the stargd process (as indicated by the given pid) to write data.
<item>-z: This option zeroes the internal tables used by the histograms.
<item>-irgap nblks: Specify the inter-read gap, nblks, (in  blocks).  When  sequential
 reads  arrive from a host there may be a small gap between successive reads.
 Normally the lookahead  algorithm  will  ignore  these gaps  providing  they
 are no larger than the average length of the group of sequential reads that
 have occurred.  By specifying  this value, you can increase this gap.
<item>-Z spinstate: This  option  will  change  the spin state of the nominated
 stargd daemon to the given spinstate.  The spin states are (State, Description,
 ASC,ASCQ):
<itemize>
<item>0, LOGICAL UNIT IS IN PROCESS OF BECOMING READY, 0x04, 0x01
<item>1, Logical unit is ready - medium access commands allowed, -, -
<item>2, LOGICAL UNIT NOT READY, MANUAL INTERVENTION REQUIRED, 0x04, 0x03
<item>3, LOGICAL UNIT HAS NOT SELF-CONFIGURED YET, 0x3e, 0x00
<item>4, LOGICAL UNIT HAS FAILED SELF-CONFIGURATION, 0x4c, 0x00
<item>stargd's spin state is used to describe the condition of the  tar<61> get
  whilst  it  is  NOT READY. When stargd is not ready to accept SCSI-2 medium
 access commands it returns a CHECK CONDITION  status to  all  medium  access
  commands,  sets the mode sense key to NOT READY and the additional mode sense
 code  and  code  qualifier  to values  depending  in  the  spin  state  value.
  Typically, when a RaidRunner boots it requires time to create  the  configured
  Raid Sets,  although it needs to start the scsi target daemons (stargd) as
 soon as possible. It does start all the  required  stargds  and set's  their
  spin  state to 0. Once the raid sets have been built and are linked to their
 stargds, the spin state is set to 1  meaning  it will allow and process SCSI-2
 medium access commands. (See the &dquot;-o&dquot; option above). The additional
 spin states of 2, 3 and 4 can be  used  by  systems with intelligent SCSI drivers
 in high availability environments.
</itemize>
</itemize>
<item>SEE ALSO: stargd
</itemize>


<sect1>NICE - Change the K9 run-queue priority of a K9 process
<p>
<itemize>
<item>SYNOPSIS: nice pid priority 
<item>DESCRIPTION: nice will change the run-queue priority of the process given
 by pid to priority.
<item>OPTIONS: 
<itemize>
<item>pid: This is the process identifier of the K9 process  whose  run-queue
 priority is to change.
<item>priority: This is the priority to set. Priorities range from 0 (lowest)
 to 9 (highest).
</itemize>
<item>SEE ALSO: K9setpriority
</itemize>

<sect1>NULL- file to throw away output in
<p>
<itemize>
<item>SYNOPSIS: bind -k null bind_point
<item>DESCRIPTION: null  is  a  special file that when written to is a infinite
 sink of data (i.e. anything can be written to it and it will be disposed of
 quickly). When null is read it is an infinite source of end-of-files. The null
 file will appear in the K9 names- pace at the bind_point.
<item>EXAMPLE Husky installs a null special file as follows:<tscreen>
<verb>bind null /dev/null
</verb></tscreen>

<item>SEE ALSO zero, log
</itemize>


<sect1>PARACC - display information about hardware parity accelerator
<p>
<itemize>
<item>SYNOPSIS: paracc
<item>DESCRIPTION: paracc will print (to standard output) information about the
 hardware parity accelerator, if installed. The  main  output  line  of interest
 to all except those debugging the RaidRunner is the first line which displays,
 in bytes, the size of the memory on the hardward parity accelerator. IE<tscreen>
<verb>Parity Memory available : 1048576
</verb></tscreen>
<verb>PAccLock@0xBF368&lcub;own=-1,cnt=1,pvt=0x0,nwait=0,name=&dquot;PAc&dquot;&rcub;
</verb>
<verb>Request failures: 0, Max Usage: 2, Alloc: 1, Free: 31
</verb>
<verb>have_paracc is 1.
</verb>
<verb>Req Fails: 0 0 0 0 0 0 0 0 0 0
</verb>
All other lines are only informative for debugging purposes.  If there
 is no  accelerator  present,  then  the Parity Memory available will be 0.
</itemize>


<sect1>PEDIT - Display/modify SCSI backend Mode Parameters Pages
<p>
<itemize>
<item>SYNOPSIS:
<itemize>
<item>pedit page_code c.s.l
<item>pedit page_code c.s.l byte_modifier_list
</itemize>
<item>DESCRIPTION: pedit will either report the SCSI pages of mode parameters
 for a given page - page_code on a given SCSI backend device c.s.l and or allow
 you to change the mode parameters. In it's first form, pedit, for a given page
 code, will print five lines.  The first is a header  for  ease  of reading,
  the  second  will  be the DEFAULT mode parameters, the second will be CHANGEABLE
 bitmask values, the third will be the CURRENT mode parameters and the last
 will be the SAVED mode parameters. In it's second form, pedit, for a given
 page code and device, will print the page codes but  also  will  apply the
 byte_modifier_list to either the CURRENT or SAVED mode parameters. The supported
 SCSI pages are

<itemize>
<item>0x1    ERROR RECOVERY page
<item>0x2    DISCONNECT page
<item>0x3    FORMAT page
<item>0x4    GEOMETRY page
<item>0x8    CACHE page
<item>0xc    NOTCH page
<item>0xa    CONTROL page
</itemize>

<item>OPTIONS
<itemize>
<item>page_code: Specify the SCSI Page Code in hex.
<item>c.s.l: Identify  the disk device to select by specifying it's channel,
 SCSI ID (rank) and SCSI LUN provided in the format &dquot;c.s.l&dquot;
<item>byte_modifier_list: The byte_modifier_list is of the form <tscreen>
<verb>C|Sbyte_no:set_val: clr_val,byte_no:set_val:clr_val,... 
</verb></tscreen>
</itemize>

where the  C  or  S prefix specifies whether you want to change the CURRENT
 or SAVED mode pages respectively. This prefix is followed by a comma separated
 list of byte modifiers in the form byte_no:set_val:clr_val where byte_no is
 the byte number to change, set_val is a mask of which bits within that byte
 to SET (to 1) and clr_val is a mask of which bits within that byte to CLEAR
 (to 0).
<item>SEE ALSO: The mode sense page references in the relevant product manual
 for the disks used in the RAID.
</itemize>


<sect1>PIPE - two way interprocess communication
<p>
<itemize>
<item>SYNOPSIS:
<itemize>
<item>bind -k pipe bind_point
<item>cat bind_point
<item>bind_point/data
<item>bind_point/ctl
<item>bind_point/data1
<item>bind_point/ctl1
</itemize>
<item>DESCRIPTION: pipe file system associates a one level directory with the
 bind_point in the K9 namespace. This device allocates two streams which are
 joined at the device end. bind_point/data and bind_point/ctl are the data and
 control channels for  one  stream while bind_point/data1 and bind_point/ctl1
 are the data and control channels for the other stream. Data  written  to 
 one  channel is available for reading at the other.  Write boundaries are preserved:
 each read terminates when the read buffer is full or after reading the last
 byte of a write, whichever comes first.
</itemize>
<sect1>PRANKS - print or set the accessible backend ranks for the current controller
<p>
<itemize>
<item>SYNOPSIS
<itemize>
<item>pranks
<item>pranks rank1 &lsqb;rank2 ... rankn&rsqb;
</itemize>
<item>DESCRIPTION: pranks,  without  any arguments will print which backend ranks
 of devices the controller, on which the command is executed, can access. If
 a rank is not accessible, then a &dquot;-1&dquot; is printed in place of the
 rank  number  (i.e scsi id of that rank).  If you wish to set which rank id's
 a controller is allowed to access then execute this command with those rank
 id's as it's arguments.

When you execute this command to set access to certain (or all) ranks,
 then the access restrictions  (if  any) are  effective  immediately.  Additionally,
  the GLOBAL environment variable BackendRanks is either defined or modified
 and when you next boot the RaidRunner, the settings you have just created will
 be set again automatically.
</itemize>
<itemize>
<item>EXAMPLE: Assume  you  have  a RaidRunner system with four ranks of backend
 devices (rank 1, 2, 3 and 4) but you want to restrict the controller's access
 to the first two as you don't have any devices installed  in  the  third  and
 forth ranks. You would execute pranks 1 2
<item>SEE ALSO: environ, sranks
</itemize>
<sect1>PRINTENV - print one or all GLOBAL environment variables
<p>
<itemize>
<item>SYNOPSIS
<itemize>
<item>printenv
<item>printenv name &lsqb;name ...&rsqb;
</itemize>
<item>DESCRIPTION: printenv prints the value (or list of values) associated with
 the GLOBAL environment variable name. If multiple GLOBAL environment variables
  are given, each value is printed on a line of it's own. When a GLOBAL environment
 variable is a list of values, each value is printed on a line of it's own.
 When printenv is called with no arguments, all GLOBAL  environment variables
 and their associated value(s) are printed, one per line. If a value is a list
 then each element of the list is separated with the vertical bar () character.
<item>NOTE: A  GLOBAL  environment  variable is one which is stored in a non
 volatile area on the RaidRunner and hence is available  between  successive
  power cycles or reboots. These variables ARE NOT the same as husky environment
 variables. The non volatile area is co-located  with  the  RaidRunner  Configuration
 area. If  the  given variable name is not a GLOBAL environment variable nothing
 is printed and no error status is set.
<item>SEE ALSO: setenv, unsetenv, rconf
<item>PROC - the process file system (device)
<item>SYNOPSIS: 
<itemize>
<item>bind -k proc bind_point
<item>cat bind_point
<item>cat bind_point/0
<item>cat bind_point/1
<item>...
<item>cat bind_point/N
<item>signal
<item>sigpgrp
<item>status
</itemize>
<item>DESCRIPTION: The proc device creates a two level directory below its bind_point.
  The first level entries are the numbers of the processes that are known currently
 to K9. The second level entries are the filenames: &dquot;signal&dquot;, &dquot;sigpgrp&dquot;
 and &dquot;status&dquot;. It is an error to read from the second level directory
 files &dquot;signal&dquot; and &dquot;sigpgrp&dquot;. When &dquot;status&dquot;
 is  read  it  returns  an ASCII string containing the following fields:
<itemize>
<item>process name
<item>process identifier (i.e. its pid)
<item>this process's parent's pid
<item>pid of process group leader
<item>process state
<item>process priority
<item>maximum stack utilization as &percnt; of available stack
<item>milliseconds of CPU time registered
<item>semaphore id (if any) this process is waiting on
</itemize>

These fields have an appropriate number of spaces between them so they
 look &dquot;reasonable&dquot; when output by ps. The process states are listed
 below:
<itemize>
<item>I      interrupted
<item>R      currently running (or has yielded control)
<item>S      stirred (signaled while waiting)
<item>W      waiting on a semaphore
<item>Z      terminated and parent not waiting
</itemize>

It is an error to write to the second level directory file &dquot;status&dquot;.
  A signal number or signal name (see kill for a list of signal names - which
 cannot be abbreviated in this case) may be written to the file &dquot;signal&dquot;.
 This action will  send a  signal  to  the associated process. If a signal number
 or name is written to the file &dquot;sigpgrp&dquot; then all the processes
 in the process group which this process belongs to will receive the signal.

<item>SEE ALSO: ps, kill
</itemize>


<sect1>PS - report process status
<p>
<itemize>
<item>SYNOPSIS: ps
<item>DESCRIPTION: ps  prints information about  all running K9 processes on
 standard out. The information output includes the process name, its process
 identification  number  (PID),  its parent's PID, process group, process state,
 the maximum percentage utilization of its stack and the milliseconds  of  CPU
 time its has used. The process states are listed below:
<itemize>
<item>I interrupted
<item>R currently running (or has yielded control)
<item>S stirred (signaled while waiting)
<item>W waiting on a semaphore
<item>Z terminated and parent not waiting
</itemize>
<item>Currently  ps is implemented as a K9 Husky script (rather than a built
 in command). The script source can be  found  in  the  file  &dquot;/bin/ps&dquot;.
  The script utilizes the file system proc.
<item>EXAMPLE:
<verb>: raid; ps
</verb>
<verb>NAME____________________PID__PPID__PGRP_S_P_ST&percnt;_TIME(ms)__SEMAPHORE+name
</verb>
<verb>hyena                   0     0     0 R 9  18 385930     deadbeef
</verb>
<verb>init                    1     0     1 W 0   9 90         8009b1a8   pau
</verb>
<verb>SCN2681_reader          4     1     4 W 0   0 0          800702a4   2rd
</verb>
<verb>SCN2681_writer          5     1     5 W 0   0 0          8007029c   2wr
</verb>
<verb>SCN2681_putter          6     1     6 W 0   0 0          800702ac   2tp
</verb>
<verb>DIO_R_drive3_q0        391     1   391 W 0   4 40120      8021a828   Ard
</verb>
<verb>DIO_R_drive0_q0        397     1   397 W 0   4 13420      8007ac64   Ard
</verb>
<verb>DIO_R_drive1_q0        404     1   404 W 0   5 25570      8007b224   Ard
</verb>
<verb>husky                  28     1     1 W 0  10 50         8013a138   pau
</verb>
<verb>cache_flusher          424     1   424 W 0  23 17700      8030c2c4   Cfr
</verb>
<verb>CIO_R_q0               426     1   426 W 0  96 2320       8030d6f4   Ard
</verb>
<verb>CIO_R_q1               427   426   426 W 0  96 2420       8030d6f4   Ard
</verb>
<verb>CIO_R_q2               428   426   426 W 0  96 2410       8030d6f4   Ard
</verb>
<verb>CIO_R_q3               429   426   426 W 0  96 2430       8030d6f4   Ard
</verb>
<verb>CIO_R_q4               430   426   426 W 0  96 2240       8030d6f4   Ard
</verb>
<verb>CIO_R_q5               431   426   426 W 0  96 2130       80c37540   Ard
</verb>
<verb>CIO_R_q6               432   426   426 W 0  96 2300       8030d6f4   Ard
</verb>
<verb>CIO_R_q7               433   426   426 W 0  96 2180       8030d6f4   Ard
</verb>
<verb>smon                    65     1     1 W 0   5 30         8008d5e4   Nsl
</verb>
<verb>DIO_R_drive2_q0        326     1   326 W 0   5 27680      8007b7e4   Ard
</verb>
<verb>/bin/ps                871    28     1 W 0   8 40         80cfd020   pau
</verb>
<verb>stargd                 107     1     1 R 0  48 23990      8007a648   Nsl
</verb>
<verb>starg_107_L_R          119   107   119 W 0   0 0          8018c608   pau
</verb>
<item>The fields are: process name, process identifier (i.e. its pid), this process's
 parent's pid, pid of process group leader, process state, process priority,
 maximum stack utilization as &percnt; of available stack, milliseconds of CPU
 time registered, semaphore id (if any) this process is waiting on along with
 the internal name of the semaphore. If a  process  is  waiting  on  a  semaphore
 then the last number is the address of the number it is waiting on.
<item>SEE ALSO: proc
</itemize>
<sect1>PSCSIRES - print SCSI-2 reservation table for all or specific monikers
<p>
<itemize>
<item>SYNOPSIS:
<itemize>
<item>pscsires
<item>pscsires moniker
</itemize>
<item>DESCRIPTION: pscsires looks up the Global SCSI-2 Reservation table for
 a given moniker (see smon or stargd) and prints  is  current  SCSI-2  reservation
 state. When  no  moniker  is given, all entries in the Global SCSI-2 Reservation
 table are printed. For each table entry to be displayed, the moniker and four
  integers  are printed  -  the controller number, host port number, reserved
 scsi id and reservor scsi id.  The combination of controller number, host 
 port  number,  and reservor scsi id can uniquely identify which host system
 issued the SCSI-2 Reserve command.  The reserved scsi id field is  used  when
  a Third-Party  reservation has been requested by the host system identified
 by the other three integers.  If all four integers are -1, then  no  scsi target
  daemon  (smon  or  stargd)  on  any  controller  or host port has reserved
 the moniker.
<item>SEE ALSO: smon, stargd, mstargd, SCSI-2 Reserve and Release Command Documentation
</itemize>
<sect1>PSTATUS - print the values of hardware status registers
<p>
<itemize>
<item>SYNOPSIS: pstatus
<item>DESCRIPTION: pstatus  will print the names and values of various hardware
 status registers. Each value is printed on a lineof it's own. Typical hardware
 status registers are BCDSW_0, BCDSW_1. Values of BCD host port SCSI ID selector
 switches
<itemize>
<item>FANS: Value of Fan status register
<item>AC_PWR: Value of AC Power supply status
<item>DC_PWR: Value of DC Power supply status
</itemize>
<item>NOTE: Not all RaidRunner models support the same status registers, so consult
 you RaidRunner model's hardware reference manual to see which are supported
 and what their values imply.
</itemize>
<sect1>RAIDACTION- script to gather/reset stats or stop/start a raid set's stargd
<p>
<itemize>
<item>SYNOPSIS: raidaction raidname up|down|getstats|getastats|zerostats
<item>DESCRIPTION: raidaction is a husky script which is used to either start
 or stop a raid set's scsi target daemon(s) (stargd) or gather/reset statistics
 about the raid set.
<item>OPTIONS :
<itemize>
<item>raidset: Specify the raid set to perform the action on.
<item>up: Start all the scsi target daemons associated with this raid set.
<item>down: Stop all the scsi target daemons associated with this raid set.
<item>getstats: Print the current statistics stored for the given raid set. 
 The first line of output is prefixed  with the  string  &dquot;RAIDSET:&dquot;
  and is the output of the stats command with arguments -r raidname -g.  The
 second line of output is prefixed with the string &dquot;CACHE:&dquot; and
 is the output of the  stats  command with arguments -c raidname -g.  The next
 line(s) are prefixed with the string &dquot;STARG: c.h.l&dquot; and is the
 output of the mstargd command with arguments -d 0 -v -h -H stargd_pid which
 stargd_pid is the  process  id of the scsi target daemon on controller c, host
 port h with scsi lun l. A line of this type is printed for each scsi target
 daemon belonging to this raid set.
<item>getastats: Print the current statistics stored for the given raid set then
 zero  all  the  stored  statistics.  By zeroing the stored statistics one can,
 through repeated timed calls to this code, form an average based on the gathered
 statistics.  The output is the same as for the getstats option.
<item>zerostats: Zero all statistics stored for the given raid set.
</itemize>
<item>SEE ALSO: stats, mstargd
</itemize>

<sect1>RAID0 - raid 0 device
<p>
<itemize>
<item>SYNOPSIS: <tscreen>
<verb>bind -k &lcub;raid0 nbackends&rcub; bind_point
</verb></tscreen>
<verb>echo moniker name=raid_set_name &gt; bind_point/ctl
</verb>
<verb>echo engage drive=driveNum qlen=queueLen fd=aFdNum blksize=blockSize name=backendname
</verb>
<verb>&lt;&gt;&lsqb;aFdNum&rsqb; backEnd &gt; bind_point/ctl
</verb>
<verb>echo disengage drive=driveNum &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum read-write &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum read-only &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum write-only &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum offline &gt; bind_point/ctl
</verb>
<verb>cat bind_point
</verb>
<verb>ctl
</verb>
<verb>data
</verb>
<verb>repair
</verb>
<verb>stats
</verb>

<item>DESCRIPTION: raid0 implements a raid 0 device. It has 1 &dquot;frontend&dquot;
 (i.e. bind_point/data) and typically multiple &dquot;backends&dquot; (i.e.
 one defined by each &dquot;engage&dquot; message with a new drive number).
 To associate an internal name (or moniker) with the raid device, send the message
  &dquot;moniker  name=internal_name&dquot;  to  the device's control file,
 bind_point/ctl. This  implementation  of  raid  0  uses  nbackends  files 
 in  its backend.  Read and write operations to the frontend (i.e. bind_point/data)
 must be in integral units of blockSize.  Each write of blockSize bytes is written
 on 1 backend  file. The backend &dquot;files&dquot; referred to here will typically
 be disks. The  name  argument allows associates the given backendname string
 with the appropriate backend. This string will be used in reporting errors
 on the running raid.

The queueLen argument must be 1 or greater and sets the maximum number
 of requests that can be put  in  a  queue  associated with each backend file.
 A daemon is spawned for each backend file to service this queue called async_io.
 Each  backend  file  first  needs  to  be  identified to the raid0 device via
 the &dquot;engage&dquot; string sent to bind_point/ctl. If required a file
 can have its association with this device terminated with a &dquot;disengage&dquot;
  string.  Once  a  backend  file  is engaged  its  access  level  can  be 
 varied  between &dquot;read-write&dquot;, &dquot;read-only&dquot;, &dquot;write-only&dquot;
 and &dquot;offline&dquot; as required. The default is &dquot;offline&dquot;
 so in most initialization situations an &dquot;access read-write&dquot; string
 needs to be sent to this device. When the file bind_point/ctl is read then
 a line is output for every engaged backend file indicating its access status
 (e.g. &dquot;drive  3:  engaged,  read-write&dquot;).  Also  backend  files
 that have been disengaged and not &dquot;re-&dquot;engaged output a line (e.g.
 &dquot;drive 5: disengaged&dquot;).

When the file bind_point/stats is read then a line is output which shows
 the cumulative number of reads and writes performed (including failures) for
 each backend of the raid device.  The format of this line is D0 r0_cnt r0_fails
 w0_cnt w0_fails; D1 r1_cnt r1_fails w1_cnt w1_fails; ... which  indicates 
 that  backend  0  (typically  the drive0) has made r0_cnt reads, w0_cnt writes,
 r0_fails read failures and w0_fails write failures and that backend 1 (drive
 1) has made r1_cnt  reads,  w1_cnt  writes,  r1_fails  read  failures  and
 w1_fails write failures and so forth for each backend in the raid set.

If the string &dquot;zerostats&dquot; is written to the file bind_point/stats
 then all cumulative read and write counts for each backend of the raid set
 are zeroed.
<item>EXAMPLE:<tscreen>
<verb>&gt; /raid0
</verb></tscreen>
<verb>bind -k &lcub;raid0 6&rcub; /raid0
</verb>
<verb>echo moniker name=R_0 &gt; /raid0/ctl
</verb>
<verb>echo engage drive=0 qlen=8 fd=7 blksize=8192 name=D0
</verb>
<verb>&lt;&gt;&lsqb;7&rsqb; /d0/data &gt; /raid0/ctl
</verb>
<verb>echo access drive=0 read-write &gt; /raid0/ctl
</verb>
<verb>...
</verb>
<verb>echo engage drive=5 qlen=8 fd=7 blksize=8192 name=D5
</verb>
<verb>&lt;&gt;&lsqb;7&rsqb; /d5/data &gt; /raid0/ctl
</verb>
<verb>echo access drive=5 read-write &gt; /raid0/ctl
</verb>

This example creates the file &dquot;/raid0&dquot; as a bind point and
 then binds the raid0 device on it.  The  first  echo command establishes the
 internal raid device name as R_0.  The subsequent echo commands are shown in
 pairs for each backend file: one sending an &dquot;engage&dquot; string and
 the other sending an &dquot;access&dquot; string to the file &dquot;/raid0/ctl&dquot;.
 Each &dquot;engage&dquot; string associates  a backend file (via file descriptor
 7) with a block size of 8192 bytes and a maximum queue length of 8. The following
 &dquot;access&dquot; string adjusts the access level of the backend file from
 &dquot;offline&dquot; (the default) to &dquot;read-write&dquot;. This is  a
 six disk raid set.

<item>NOTES: The size of the resultant  raid  set  will be the size of the smallest
 backend multiplied by the number of data backends adjusted downwards to align
 to be a multiple of the raid set's blocksize (blockSize).
<item>SEE ALSO: raid1, raid3, raid4, raid5
</itemize>


<sect1>RAID1 - raid 1 device
<p>
<itemize>
<item>SYNOPSIS: <tscreen>
<verb>bind -k raid1 bind_point
</verb></tscreen>
<verb>echo moniker name=raid_set_name &gt; bind_point/ctl
</verb>
<verb>echo engage drive=driveNum qlen=queueLen fd=aFdNum blksize=blockSize name=backendname
</verb>
<verb>&lt;&gt;&lsqb;aFdNum&rsqb; backEnd &gt; bind_point/ctl
</verb>
<verb>echo disengage drive=driveNum &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum read-write &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum read-only &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum write-only &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum offline &gt; bind_point/ctl
</verb>
<verb>cat bind_point
</verb>
<verb>ctl
</verb>
<verb>data
</verb>
<verb>repair
</verb>
<verb>stats
</verb>

<item>DESCRIPTION: raid1  implements  a  raid  1 device. Raid 1 is also known
 as &dquot;mirroring&dquot;.  It has 1 &dquot;frontend&dquot; (i.e. bind_point/data)
 and 2 &dquot;backends&dquot; (i.e. one defined by each &dquot;engage&dquot;
 message with a new drive number). To associate an internal name (or moniker)
 with the raid device,  send  the  message  &dquot;moniker  name=internal_name&dquot;
 to the device's control file, bind_point/ctl. Read  and  write  operations
  to  the  frontend (i.e. bind_point/data) must be in integral units of blockSize.
 Each write of blockSize bytes is written on both backend files.  A read of
 blockSize bytes needs only to read 1 backend file (unless there is a problem).
  The backend file chosen to do the read is the one calculated to have its heads
 closer to the required block. The backend &dquot;files&dquot; referred to here
 will typically be disks.

The &dquot;logical&dquot; block size is currently 512 bytes and the given
 blockSize must be a power of 2 times  512  (i.e.  2**n  *  512 bytes).  If,
 for example, the blockSize was 8 Kb then a write of 8 Kb would cause both backend
 files to have that 8 Kb written to them.  An 8 Kb read would cause the file
 calculated to have its &dquot;heads&dquot; closer to be read. If this  file
  was  marked &dquot;offline&dquot;, &dquot;write-only&dquot; or reported an
 IO error then the other file would be read.

The  queueLen  argument  must  be 1 or greater and sets the maximum number
 of requests that can be put in a queue associated with each backend file. A
 daemon is spawned for each backend file to service this queue called async_io.
 The name argument allows associates the given backendname string with the appropriate
 backend. This string will be  used  in reporting errors on the running raid.

Each  backend  file  first  needs  to  be  identified to the raid1 device
 via the &dquot;engage&dquot; string sent to bind_point/ctl. If required a file
 can have its association with this device terminated with a &dquot;disengage&dquot;
  string.  Once  a  backend  file  is engaged  its  access  level  can  be 
 varied  between &dquot;read-write&dquot;, &dquot;read-only&dquot;, &dquot;write-only&dquot;
 and &dquot;offline&dquot; as required. The default is &dquot;offline&dquot;
 so in most initialization situations an &dquot;access read-write&dquot; string
 needs to be sent to this device.

When the file bind_point/ctl is read then a line is output for every engaged
 backend file indicating its access status (e.g. &dquot;drive  3: engaged, read-write&dquot;).
  Also  backend  files that have been disengaged and not &dquot;re-&dquot;engaged
 output a line (e.g. &dquot;drive 5: disengaged&dquot;).

When the file bind_point/stats is read then a line is output which shows
 the cumulative number of reads and writes performed (including failures) for
 each backend of the raid device.  The format of this line is: 
<verb>D0 r0_cnt r0_fails w0_cnt w0_fails; D1 r1_cnt r1_fails w1_cnt w1_fails;
</verb>

which  indicates  that  backend  0  (typically  the drive0) has made r0_cnt
 reads, w0_cnt writes, r0_fails read failures and w0_fails write failures and
 that backend 1 (drive 1) has made r1_cnt  reads,  w1_cnt  writes,  r1_fails
  read  failures  and w1_fails write failures.

If the string &dquot;zerostats&dquot; is written to the file bind_point/stats
 then all cumulative read and write counts for each backend of the raid set
 are zeroed.
<item>EXAMPLE<tscreen>
<verb>&gt; /raid1
</verb></tscreen>
<verb>bind -k raid1 /raid1
</verb>
<verb>echo moniker name=R_1 &gt; /raid1/ctl
</verb>
<verb>echo engage drive=0 qlen=8 fd=7 blksize=8192 name=D1
</verb>
<verb>&lt;&gt;&lsqb;7&rsqb; /d0/data &gt; /raid1/ctl
</verb>
<verb>echo access drive=0 read-write &gt; /raid1/ctl
</verb>
<verb>echo engage drive=1 qlen=8 fd=7 blksize=8192 name=D5
</verb>
<verb>&lt;&gt;&lsqb;7&rsqb; /d5/data &gt; /raid1/ctl
</verb>
<verb>echo access drive=1 read-write &gt; /raid1/ctl
</verb>

This example creates the file &dquot;/raid1&dquot; as a bind point and
 then binds the raid1 device on it.  The  first  echo command

establishes  the  internal  raid  device  name as R_1.  The subsequent
 echo commands are shown in pairs for both backend files: one sending an &dquot;engage&dquot;
 string and the other sending an &dquot;access&dquot; string  to  the  file
  &dquot;/raid1/ctl&dquot;.  Each  &dquot;engage&dquot; string  associates 
 a  backend file (via file descriptor 7) with a block size of 8192 bytes and
 a maximum queue length of 8. The following &dquot;access&dquot; string adjusts
 the access level of the backend file from &dquot;offline&dquot; (the default)
 to &dquot;read-write&dquot;.
<item>NOTES: The size of the resultant raid set will be the size of the smallest
 backend multiplied by the number of data backends  (here just 1 as we are a
 mirror) adjusted downwards to align to be a multiple of the raid set's blocksize
 (blockSize).
<item>SEE ALSO: raid0, raid3, raid4, raid5
</itemize>

<sect1>RAID3 - raid 3 device
<p>
<itemize>
<item>SYNOPSIS<tscreen>
<verb>bind -k &lcub;raid3 nbackends&rcub; bind_point
</verb></tscreen>
<verb>echo moniker name=raid_set_name &gt; bind_point/ctl
</verb>
<verb>echo engage drive=driveNum qlen=queueLen fd=aFdNum blksize=blockSize name=backendname
</verb>
<verb>&lt;&gt;&lsqb;aFdNum&rsqb; backEnd &gt; bind_point/ctl
</verb>
<verb>echo disengage drive=driveNum &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum read-write &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum read-only &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum write-only &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum offline &gt; bind_point/ctl
</verb>
<verb>cat bind_point
</verb>
<verb>ctl
</verb>
<verb>data
</verb>
<verb>repair
</verb>
<verb>stats
</verb>

<item>DESCRIPTION: raid3  implements  a  raid  3 device. It has 1 &dquot;frontend&dquot;
 (i.e. bind_point/data) and typically multiple &dquot;backends&dquot; (i.e.
 one defined by each &dquot;engage&dquot; message with a new drive number).

To associate an internal name (or moniker) with the raid device,  send
  the  message  &dquot;moniker  name=internal_name&dquot;  to  the device's
 control file, bind_point/ctl.

This  implementation  of  raid  3  uses  at  least  3 files in its backend.
  Read and write operations to the frontend (i.e. bind_point/data) must be in
 integral units of blockSize. Each write of blockSize bytes  is  striped  (i.e.
  divided  evenly) across  (nbackends  - 1) files with the &dquot;parity&dquot;
 on the other file. Subsequent writes will NOT rotate the file being used to
 store parity. &lsqb;This rotation is a slight extension of the original raid
 3 definition.&rsqb; The backend &dquot;files&dquot; referred to  here will
 typically be disks.

The  &dquot;logical&dquot;  block  size is currently 512 bytes and the
 given blockSize must be an integral multiple of (nbackends - 1) * 512 If, for
 example, the blockSize was 8 Kb and there were 5 backends then a write of 8
 Kb would cause 4  backend  files  to have  2  Kb  written on them and the other
 backend file to have 2 Kb of parity written on it. An 8 Kb read would cause
 the 4 files known to hold the data (as distinct from the parity) to be read.
 If any one  of  these  files  was  marked  &dquot;offline&dquot;, &dquot;write-only&dquot;
 or reported an IO error then the 5th file containing the parity would be read
 and the 8 Kb block reconstructed.

The queueLen argument must be 1 or greater and sets the maximum number
 of requests that can be put  in  a  queue  associated with each backend file.
 A daemon is spawned for each backend file to service this queue called async_io.

The  name  argument allows associates the given backendname string with
 the appropriate backend. This string will be used in reporting errors on the
 running raid.

Each backend file first needs to be identified to the raid3 device via
  the  &dquot;engage&dquot;  string  sent  to  bind_point/ctl.  If required
  a  file  can  have  its  association with this device terminated with a &dquot;disengage&dquot;
 string. Once a backend file is engaged its access level can be varied between
 &dquot;read-write&dquot;,  &dquot;read-only&dquot;,  &dquot;write-only&dquot;
  and  &dquot;offline&dquot;  as  required.  The default is &dquot;offline&dquot;
 so in most initialization situations an &dquot;access read-write&dquot; string
 needs to be sent to this device. When the file bind_point/ctl is read then
 a line is output for every engaged backend file indicating its access status
 (e.g. &dquot;drive 3: engaged, read-write&dquot;). Also backend files that
 have been disengaged and  not  &dquot;re-&dquot;engaged  output  a  line  (e.g.
 &dquot;drive 5: disengaged&dquot;).

When the file bind_point/stats is read then a line is output which shows
 the cumulative number of reads and writes performed (including failures) for
 each backend of the raid device.  The format of this line is
<verb>D0 r0_cnt r0_fails w0_cnt w0_fails; D1 r1_cnt r1_fails w1_cnt w1_fails;
 ...
</verb>

which indicates that backend 0 (typically the drive0) has made r0_cnt reads,
  w0_cnt  writes,  r0_fails  read  failures  and w0_fails  write  failures 
 and  that  backend  1  (drive 1) has made r1_cnt reads, w1_cnt writes, r1_fails
 read failures and w1_fails write failures and so forth for each backend in
 the raid set.

If the string &dquot;zerostats&dquot; is written to the file bind_point/stats
 then all cumulative read and write counts for each backend of the raid set
 are zeroed.
<item>EXAMPLE:<tscreen>
<verb>&gt; /raid3
</verb></tscreen>
<verb>bind -k &lcub;raid3 5&rcub; /raid3
</verb>
<verb>echo moniker name=R_3 &gt; /raid3/ctl
</verb>
<verb>echo engage drive=0 qlen=8 fd=7 blksize=8192 name=D0
</verb>
<verb>&lt;&gt;&lsqb;7&rsqb; /d0/data &gt; /raid3/ctl
</verb>
<verb>echo access drive=0 read-write &gt; /raid3/ctl
</verb>
<verb>...
</verb>
<verb>echo engage drive=5 qlen=8 fd=7 blksize=8192 name=D5
</verb>
<verb>&lt;&gt;&lsqb;7&rsqb; /d5/data &gt; /raid3/ctl
</verb>
<verb>echo access drive=5 read-write &gt; /raid3/ctl
</verb>

This  example  creates  the file &dquot;/raid3&dquot; as a bind point and
 then binds the raid3 device on it.  The first echo command establishes the
 internal raid device name as R_3.  The subsequent echo commands are shown 
 in  pairs  for  each  backend file: one sending an &dquot;engage&dquot; string
 and the other sending an &dquot;access&dquot; string to the file &dquot;/raid3/ctl&dquot;.
 Each &dquot;engage&dquot; string associates a backend file (via file descriptor
 7) with a block size of 8192 bytes and a maximum queue length of 8. The  following
  &dquot;access&dquot; string adjusts the access level of the backend file from
 &dquot;offline&dquot; (the default) to &dquot;read-write&dquot;. This is a
 6 disk raid set.
<item>NOTES: The size of the resultant raid set will be the size of the smallest
 backend  multiplied  by  the  number  of  data  backends adjusted downwards
 to align to be a multiple of the raid set's blocksize (blockSize).
<item>SEE ALSO: raid0, raid1, raid4, raid5
</itemize>



<sect1>RAID4 - raid 4 device
<p>

 
<itemize>
<item>SYNOPSIS:<tscreen>
<verb>bind -k &lcub;raid4 nbackends&rcub; bind_point
</verb></tscreen>
<verb>echo moniker name=raid_set_name &gt; bind_point/ctl
</verb>
<verb>echo engage drive=driveNum qlen=queueLen fd=aFdNum blksize=blockSize name=backendname
</verb>
<verb>&lt;&gt;&lsqb;aFdNum&rsqb; backEnd &gt; bind_point/ctl
</verb>
<verb>echo disengage drive=driveNum &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum read-write &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum read-only &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum write-only &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum offline &gt; bind_point/ctl
</verb>
<verb>cat bind_point
</verb>
<verb>ctl
</verb>
<verb>data
</verb>
<verb>repair
</verb>
<verb>stats
</verb>

<item>DESCRIPTION: raid4 implements a raid 4 device. It has 1 &dquot;frontend&dquot;
 (i.e. bind_point/data) and typically multiple &dquot;backends&dquot; (i.e.
 one defined by each &dquot;engage&dquot; message with a new drive number).
 To associate an internal name (or moniker) with the raid device,  send the
 message &dquot;moniker  name=internal_name&dquot;  to  the device's control
 file, bind_point/ctl. This  implementation  of  raid  4  uses  at  least  3
 files in its backend.  Read and write operations to the frontend (i.e. bind_point/data)
 must be in integral units of blockSize. Each write of blockSize bytes is written
 on  1 backend  file. Its neighboring  (nbackends - 2) files need to be read
 at the same offset to calculate a new parity block which needs to be re- written.
 The nbackends blocks at the same offset on the nbackends backend files are
 called a slice.  The  parity  block  is, like in raid3, fixed as the last backend.
 A read of blockSize bytes needs only to read 1 backend file (unless there is
 a problem). The backend &dquot;files&dquot; referred to here will typically
 be disks.

The &dquot;logical&dquot; block size is currently 512 bytes and the given
 blockSize must be an integral multiple of (nbackends  -  1)  * 512  If, for
 example, the blockSize was 8 Kb then a write of 8 Kb would cause 1 backend
 file to have that 8 Kb written to it with the other (nbackends - 2) non-parity
 files in that slice having 8 Kb read from them in order to generate  a  new
  8  Kb parity  block  which  is then written to the parity file in this slice.
  An 8 Kb read would cause the file known to hold the data (as distinct from
 the parity) to be read. If this file was marked &dquot;offline&dquot;, &dquot;write-only&dquot;
 or reported an IO error  then the  other  ((nbackends  -  1) files in the slice
 (i.e.  (nbackends - 2) data and 1 parity) would be read and the 8 Kb block
 reconstructed.

The queueLen argument must be 1 or greater and sets the maximum number
 of requests that can be put  in  a  queue  associated with each backend file.
 A daemon is spawned for each backend file to service this queue called async_io.

The  name  argument allows associates the given backendname string with
 the appropriate backend. This string will be used in reporting errors on the
 running raid.

Each backend file first needs to be identified to the raid5 device via
  the  &dquot;engage&dquot;  string  sent  to  bind_point/ctl.  If  required
  a  file  can  have  its  association with this device terminated with a &dquot;disengage&dquot;
 string. Once a backend file is engaged its access level can be varied between
 &dquot;read-write&dquot;,  &dquot;read-only&dquot;,  &dquot;write-only&dquot;
  and  &dquot;offline&dquot;  as  required.  The default is &dquot;offline&dquot;
 so in most initialization situations an &dquot;access read-write&dquot; string
 needs to be sent to this device.

When the file bind_point/ctl is read then a line is output for every engaged
 backend file indicating its access status (e.g. &dquot;drive 3: engaged, read-write&dquot;).
 Also backend files that have been disengaged and  not  &dquot;re-&dquot;engaged
  output  a  line  (e.g. &dquot;drive 5: disengaged&dquot;).

When the file bind_point/stats is read then a line is output which shows
 the cumulative number of reads and writes performed (including failures) for
 each backend of the raid device.  The format of this line is
<verb>D0 r0_cnt r0_fails w0_cnt w0_fails; D1 r1_cnt r1_fails w1_cnt w1_fails;
 ...
</verb>

which indicates that backend 0 (typically the drive0) has made r0_cnt reads,
 w0_cnt  writes,  r0_fails read failures and w0_fails write failures and that
  backend  1  (drive 1) has made r1_cnt reads, w1_cnt writes, r1_fails read
 failures and w1_fails write failures and so forth for each backend in the raid
 set.

If the string &dquot;zerostats&dquot; is written to the file bind_point/stats
 then all cumulative read and write counts for each backend of the raid set
 are zeroed.

<item>EXAMPLE<tscreen>
<verb>&gt; /raid4
</verb></tscreen>
<verb>bind -k &lcub;raid4 5&rcub; /raid4
</verb>
<verb>echo moniker name=R_4 &gt; /raid4/ctl
</verb>
<verb>echo engage drive=0 qlen=8 fd=7 blksize=8192 name=D0
</verb>
<verb>&lt;&gt;&lsqb;7&rsqb; /d0/data &gt; /raid4/ctl
</verb>
<verb>echo access drive=0 read-write &gt; /raid4/ctl
</verb>
<verb>...
</verb>
<verb>echo engage drive=5 qlen=8 fd=7 blksize=8192 name=D5
</verb>
<verb>&lt;&gt;&lsqb;7&rsqb; /d5/data &gt; /raid4/ctl
</verb>
<verb>echo access drive=5 read-write &gt; /raid4/ctl
</verb>


This  example  creates  the file &dquot;/raid4&dquot; as a bind point and
 then binds the raid4 device on it.  The first echo command establishes the
 internal raid device name as R_4.  The subsequent echo commands are shown 
 in  pairs  for  each  backend file: one sending an &dquot;engage&dquot; string
 and the other sending an &dquot;access&dquot; string to the file &dquot;/raid4/ctl&dquot;.
 Each &dquot;engage&dquot; string associates a backend file (via file descriptor
 7) with a block size of 8192 bytes and a maximum queue length of 8. The  following
  &dquot;access&dquot; string adjusts the access level of the backend file from
 &dquot;offline&dquot; (the default) to &dquot;read-write&dquot;. This is a
 six disk raid set.

<item>NOTES: The size of the resultant raid set will be the size of the smallest
 backend  multiplied  by  the  number  of  data  backends adjusted downwards
 to align to be a multiple of the raid set's blocksize (blockSize).
<item>SEE ALSO: raid0, raid1, raid3, raid5
</itemize>


<sect1>RAID5 - raid 5 device
<p>
<itemize>
<item>SYNOPSIS<tscreen>
<verb>bind -k &lcub;raid5 nbackends&rcub; bind_point
</verb></tscreen>
<verb>echo moniker name=raid_set_name &gt; bind_point/ctl
</verb>
<verb>echo engage drive=driveNum qlen=queueLen fd=aFdNum blksize=blockSize name=backendname
</verb>
<verb>&lt;&gt;&lsqb;aFdNum&rsqb; backEnd &gt; bind_point/ctl
</verb>
<verb>echo disengage drive=driveNum &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum read-write &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum read-only &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum write-only &gt; bind_point/ctl
</verb>
<verb>echo access drive=driveNum offline &gt; bind_point/ctl
</verb>
<verb>cat bind_point
</verb>
<verb>ctl
</verb>
<verb>data
</verb>
<verb>repair
</verb>
<verb>stats
</verb>

<item>DESCRIPTION: raid5  implements a raid 5 device. It has 1 &dquot;frontend&dquot;
 (i.e. bind_point/data) and typically multiple &dquot;backends&dquot; (i.e.
 one defined by each &dquot;engage&dquot; message with a new drive number).

To associate an internal name (or moniker) with the raid device, send the
 message  &dquot;moniker  name=internal_name&dquot; to the device's control
 file, bind_point/ctl.

This  implementation  of  raid 5 uses at least 3 files in its backend.
  Read and write operations to the frontend (i.e. bind_point/data) must be in
 integral units of blockSize. Each write of blockSize bytes is written  on 1
 backend file. Its neighboring (nbackends - 2) files need to be read at the
 same offset to calculate a new parity block which needs to be re-written. The
 nbackends blocks at the  same  offset  on the  nbackends backend files are
 called a slice. The parity block is rotated from one slice to the next. A read
 of blockSize bytes needs only to read 1 backend file (unless there is a  problem).
  The  backend &dquot;files&dquot; referred to here will typically be disks.

The  &dquot;logical&dquot; block size is currently 512 bytes and the given
 blockSize must be an integral multiple of (nbackends - 1) * 512 If, for example,
 the blockSize was 8 Kb then a write of 8 Kb would cause 1 backend file  to
 have that 8 Kb written to it with the other (nbackends - 2) non-parity files
 in that slice having 8 Kb read from them in order to generate a new 8 Kb parity
 block which is then written to the parity file in this slice.  An 8 Kb read
 would cause the file known to hold the data (as distinct from the parity) to
 be read. If this file was marked &dquot;offline&dquot;, &dquot;write-only&dquot;
 or reported an IO error then the  other ((nbackends - 1) files in the slice
 (i.e.  (nbackends - 2) data and 1 parity) would be read and the 8 Kb block
 reconstructed.

The queueLen argument must be 1 or greater and sets the maximum number
 of requests that can be put in  a queue associated with each backend file.
 A daemon is spawned for each backend file to service this queue called async_io.

The name argument allows associates the given backendname string  with
  the  appropriate  backend.  This string will be used in reporting errors on
 the running raid.

Each  backend  file  first  needs  to  be identified to the raid5 device
 via the &dquot;engage&dquot; string sent to bind_point/ctl. If required a file
 can have its association with this device terminated with  a  &dquot;disengage&dquot;
 string. Once a backend file is engaged its access level can be varied between
 &dquot;read-write&dquot;, &dquot;read- only&dquot;, &dquot;write-only&dquot;
 and &dquot;offline&dquot; as required. The default is &dquot;offline&dquot;
 so in most initialization situations an &dquot;access read-write&dquot; string
 needs to be sent to this device.

When the file bind_point/ctl is read then a line is output for every engaged
 backend file indicating its access status (e.g. &dquot;drive 3: engaged, read-write&dquot;).
 Also backend files that have  been  disengaged  and not &dquot;re-&dquot;engaged
 output a line (e.g. &dquot;drive 5: disengaged&dquot;).

When  the file bind_point/stats is read then a line is output which shows
 the cumulative number of reads and writes performed (including failures) for
 each backend of the raid device.  The format of this  line is
<verb>D0 r0_cnt r0_fails w0_cnt w0_fails; D1 r1_cnt r1_fails w1_cnt w1_fails;
 ...
</verb>

which  indicates  that  backend  0 (typically the drive0) has made r0_cnt
 reads, w0_cnt writes, r0_fails read failures and w0_fails write failures and
 that backend 1 (drive 1) has  made  r1_cnt  reads,  w1_cnt writes,  r1_fails
  read  failures  and w1_fails write failures and so forth for each backend
 in the raid set.

If the string &dquot;zerostats&dquot; is written to the file bind_point/stats
 then all  cumulative  read  and  write counts for each backend of the raid
 set are zeroed.

<item>EXAMPLE<tscreen>
<verb>&gt; /raid5
</verb></tscreen>
<verb>bind -k &lcub;raid5 5&rcub; /raid5
</verb>
<verb>echo moniker name=R_5 &gt; /raid5/ctl
</verb>
<verb>echo engage drive=0 qlen=8 fd=7 blksize=8192 name=D0
</verb>
<verb>&lt;&gt;&lsqb;7&rsqb; /d0/data &gt; /raid5/ctl
</verb>
<verb>echo access drive=0 read-write &gt; /raid5/ctl
</verb>
<verb>...
</verb>
<verb>echo engage drive=5 qlen=8 fd=7 blksize=8192 name=D1
</verb>
<verb>&lt;&gt;&lsqb;7&rsqb; /d5/data &gt; /raid5/ctl
</verb>
<verb>echo access drive=5 read-write &gt; /raid5/ctl
</verb>

This example creates the file &dquot;/raid5&dquot; as a bind point and
 then binds the raid5 device on it.  The first echo command establishes the
 internal raid device name as R_5. The subsequent echo commands are shown  in
  pairs for each backend file: one sending an &dquot;engage&dquot; string and
 the other sending an &dquot;access&dquot; string to the file &dquot;/raid5/ctl&dquot;.
 Each &dquot;engage&dquot; string associates a backend file (via file descriptor
  7) with  a  block size of 8192 bytes and a maximum queue length of 8. The
 following &dquot;access&dquot; string adjusts the access level of the backend
 file from &dquot;offline&dquot; (the default) to &dquot;read-write&dquot;.
 This is a six disk raid set.

<item>NOTES: The  size of the resultant raid set will be the size of the smallest
 backend multiplied by the number of data backends adjusted downwards to align
 to be a multiple of the raid set's blocksize (blockSize).
<item>SEE ALSO: raid0, raid1, raid3, raid4
</itemize>


<sect1>RAM - ram based file system
<p>
<itemize>
<item>SYNOPSIS: bind -k ram bind_point 
<item>DESCRIPTION: The ram file system uses memory on the target system's heap
 to support an hierarchical file system. Typically ram is the root file system
 in a husky environment. Unlike a normal file system ram lacks persistence.
 Therefore (assuming the heap resides in  _non_  battery  backed  up  RAM) when
 the target system loses power, the contents of the ram file system are lost.
 This is similar to the way the &dquot;/tmp&dquot; file system works in Unix.
<item>SEE ALSO: mem
</itemize>
<sect1>RANDIO - simulate random reads and writes
<p>
<itemize>
<item>SYNOPSIS: randio -d device -n nop &lsqb;-b cnt&rsqb; &lsqb;-f fill_ch&rsqb;
 &lsqb;-i init_ch&rsqb; &lsqb;-o offset&rsqb; &lsqb;-s size&rsqb; &lsqb;-G grp_size&rsqb;
 &lsqb;-S seed&rsqb; &lsqb;-X xfer_size&rsqb; &lsqb;-M rdwr|rdonly&rsqb; &lsqb;-T
 seq|ran&rsqb; &lsqb;-vBDON&rsqb;
<item>DESCRIPTION: randio defines a range on the device from the start of the
 device to it's end, or for a length of size IN 512-byte BLOCKS, if specified,
  in  which to  perform.  nop random write then read operations. All reads and
 writes are in multiples of 512 byte blocks.  First, every  block  in  the 
 given range is initialized with a specific pattern.  Then for each operation,
 a random location in the range is chosen and a random number of blocks  are
 written  with  a  specific  data pattern.  Once nop write operations have occurred,
 nop reads  are  performed  at  the  appropriate  locations  and lengths  to
  verify the previously written data.  Lastly, all data on the device is verified.
  That is, any unwritten block should  have  only  the initialization  pattern
 and any block that was written to should have the appropriate data pattern.
 When a write of a given length occurs, each 512  byte  block  within  the write
  has  a  header  containing  the operation number, the start of the write location,
 the length of write and the data fill pattern.  The  rest of each 512 byte
 block is initialized with a fill pattern. The  output  of  this command provides
 the I/O transfer rates in Megabytes (MB) and million bytes (Mb) for the three
 phases of I/O, that is  sequential<61> writes, random writes then reads, and finally
 sequential reads. The size and offset values may have a suffix.
<item>OPTIONS:
<itemize>
<item>-b cnt: Restrict all read and write operations to be multiples of cnt x
 512 blocks. The default is 1.
<item>-f fill_ch: The data fill pattern used in writes should be fill_ch. fill_ch
 must be specified as a hex number. The default is 0x7F.
<item>-i init_ch: The fill pattern used when initialising the device should be
 init_ch. fill_ch must be specified as a hex number. The default is 0x00.
<item>-o offset: All reads and writes are to be performed offset 512-byte BLOCKS
 into the device. All reported values will be relative to this offset. The default
 is 0 i.e the start of the device.
<item>-s size: The size, in 512-byte BLOCKS, of the range upon which we perform
 the io.
<item>-v: Run in verbose mode printing out initialization  information, and the
 final verification of the whole specified range on the device. If a second
 -v is given then details of individual read and  write operations are printed.
<item>-B: Align all random write locations to be a multiple of cnt x 512. Where
 cnt is specified by the -b option. This is useful when writing to raw raid
 devices which require both a fixed write size multiple and an aligned &dquot;start
 of write&dquot; address.
<item>-G grp_siz: Normally, randio performs nop  writes  then  nop  reads.  
 The  -G option  can  change  this  to  perform grp_siz writes then grp_siz
 reads looping until nop  operations  have  occurred.  The  default &dquot;group
  size&dquot;  if  nop  operations. If grp_siz is negative, then a random group
 size is chosen.
<item>-M rdwr|rdonly: By default, a destructive read-write test is performed
 (-M  rdwr). To  run  randio in a non-destructive way, specify this option with
 the sub-option of rdonly. This will result in randio only performing reads.
<item>-N: By default, data read is always compared against what was written.
 By specifying this option, the comparison will not be  made.  This option is
 usefull when you are only concerned with performing random reads and writes
 and not if the data corrupts.
<item>-O: By default, the random write locations and  sizes  are  chosen  so
 that  they  overlap.  By specifying this option, overlapped writes can NOT
 occur.  By careful when using this option if  your  device is small.
<item>-S seed: Specify a seed for the random number generators.
<item>-T ran|seq: By  default, randio performs a sequence of sequential writes,
 random writes then reads and finally sequential reads. To  have  only the 
 sequential  activity  performed,  use  the -T seq option. The default is -T
 ran.
<item>-X xfer_size: Restrict the maximum write size to be xfer_size  512-byte
  BLOCKS. The default is 256 blocks - 128K bytes.
</itemize>
<item>SEE ALSO: speedtst, suffix
</itemize>


<sect1>RCONF, SPOOL, HCONF, MCONF, CORRUPT-CONFIG - raid configuration and spares
 management
<p>
<itemize>
<item>SYNOPSIS :
<itemize>
<item>rconf -add -type raidtype -name raidname  -size raidsize -iomode read-write|read-only|write-only
 -iosize raid- chunksize -hostif mflag controller host_port  scsi_lun  -backendsize
  backends_size  -backends  backend1,backend2,...,backendn  &lsqb;-boot  auto|manual&rsqb;
  &lsqb;-cache  raidcachesize&rsqb;  &lsqb;-state active|inactive&rsqb; &lsqb;-usespares
 on|off&rsqb; &lsqb;-usezoneio on|off&rsqb; &lsqb;-qlen nqueues&rsqb; &lsqb;-stargs
 &lcub;xstargd_args&rcub;&rsqb; &lsqb;-hostif mflag controller host_port scsi_lun&rsqb;
<item>rconf -delete raidname
<item>rconf -list &lsqb;raidname&rsqb; &lsqb;-v&rsqb;
<item>rconf &lsqb;-v&rsqb;
<item>rconf -mkfaulty -name raidname -drive drive_no
<item>rconf -modify -name raidname &lsqb;-iomode read-write|read-only|write-only&rsqb;
 &lsqb;-newname newraidname&rsqb;  &lsqb;-hostif  mflag controller host_port
 scsi_lun&rsqb; &lsqb;-boot auto|manual&rsqb; &lsqb;-cache raidcachesize&rsqb;
 &lsqb;-state active|inactive&rsqb; &lsqb;-usespares on|off&rsqb; &lsqb;-usezoneio
 on|off&rsqb; &lsqb;-qlen nqueues&rsqb; &lsqb;-stargs &lcub;xstargd_args&rcub;&rsqb;
<item>rconf -rebuild -name raidname -drive drive_no &lsqb;-spare spare_backend&rsqb;
<item>rconf -repair -name raidname -drive drive_no -action start|finish &lsqb;-depth
 value&rsqb;
<item>rconf -replace -name raidname -backend backendn -action start|finish &lsqb;-depth
 value&rsqb;
<item>rconf -unrepair -name raidname -backend backendn -drive drive_no -depth
 value
<item>rconf -init
<item>rconf -fullinit
<item>rconf -check
<item>rconf -maxiochunk
<item>rconf -validate
<item>rconf -syslog
<item>rconf -size
<item>spool -add -name backend -backendsize backends_size -type hot|warm &lsqb;-ctlr
 controller_number&rsqb;
<item>spool -delete -name backend
<item>spool -list
<item>spool
<item>hconf -delete controller hostport
<item>hconf -list &lsqb;controller hostport&rsqb;
<item>hconf
<item>hconf -modify controller hostport scsi_id
<item>mconf -add controller hostport scsi_lun &lsqb;blkprotocol&rsqb;
<item>mconf -delete controller hostport scsi_lun
<item>mconf -sml 
<item>mconf -smldelete controller hostport
<item>mconf -list &lsqb;controller&rsqb;
<item>mconf &lsqb;-C&rsqb; &lsqb;-c&rsqb; corrupt-config
</itemize>
<item>DESCRIPTION: rconf, hconf, mconf and spool manipulate raid set definitions,
 host port connections and the spares pool on  a RaidRunner.  All  information
  is  stored  the  RaidRunner  configuration  area  which  is  stored in the
 file /dev/flash/conf and duplicated on every disk (/dev/hd/.../rconfig) on
 the RaidRunner.  The corrupt-config command will corrupt the configuration
 areas and immediately reboot the RaidRunner. 
<itemize>
<item>Raid Sets: A Raid Set has the following attributes
<itemize>
<item>Type : the  Raid  Type - either 0 (stripped backends), 1 (mirrored backends),
 3 (stripped backends with parity on one backend), 5 (stripped backends with
 parity spread across all backends).
<item>Name : the Raid Set's unique name used to make identification and access
 easier.  A Raid Set's name must start with an alphabetic character and then
 have alphanumeric elsewhere. The maximum length of the name is 32 characters.
<item>IOmode: the mode of access to the Raid Set. Access modes can be either
 read-write, read-only or write-only.
<item>Size: the size (in 512 byte blocks) of the raid set if it's to be less
 than the calculated size.  Normally  a raid  set's size is a function of the
 size of the raid set's backends (i.e type 0 - sum of backends, 1 - size of
 one backend, 3/5 - sum of backends less one). The Size must be a multiple of
 of the IOsize.
<item>IOsize: the size (in bytes) of io for read and write operations to the
 raid set. This is  commonly  called  the chunksize.
<item>Cachesize: the  size (in bytes) of any cache that will front-end the raid
 set. The cache size must be a minimum of 256K bytes (quarter megabyte).  The
 cache size must also be a multiple of the raid set's IOsize.
<item>Host Interface(s): the interfaces to use for access by a host. A raid set
 can be  either  single-ported  or  multi-ported. That  is  to  say,  a  raid
 set can present different scsi disks all directed at itself. Naturally, the
 host(s) that access these disks must co-operate to ensure data integrity. 
 Each  host  interface  is  a quartet  of  -  a master/slave access flag, the
 controller number, the host port on that controller and lastly the SCSI LUN
 that the raid set should propagate on the host port.  The master/slave access
  flag is  used  at  boot  time to configure the Host Interface's SCSI target
 daemon into either a full access (and hence spun up) master SCSI target or
 a minimal access (and hence spun down) slave SCSI target. See details on the
 -Z option on the mstargd command. This master/slave concept can be used by
 co-opera- tive hosts to share access to a single raid set via multiple SCSI
 target daemons.  A raid set can  only be multi-ported within a controller.
<item>Backends: the list of the raid set's backends. Backends can either be disks
 or other raid sets.
<item>Backendsize: the size (in 512 byte blocks) of the raid set backends
<item>Bootmode: the  boot mode of the raid set. It can either be autoboot or
 manual.  For the former, when the RaidRunner boots, the raid set is automatically
 made available on the host  interface  specified  and  in  the later case,
 it must be manually made available.
<item>State : this is the State of the raid set. The state of a raid set can
 either be active or inactive. If active, then the raid set's data is available
 for access. If inactive, then data on the raid set is not  avail- able and
 hence the raid set is in a quiescent state.
<item> ZoneioUsage: this is a flag to indicate to the cache filesystem that all
 I/O to this raid set be optimized for backend reads and writes based on the
 backends zone (notch) pages.
<item>SparesUsage: this is a flag to indicate whether the raid set is to use
 spares. It's value can be either on or off.
<item>QueueLen: this is the maximum number of requests than can be put in an
 io queue associated with each  backend  of the raid set. It's value must be
 1 or greater.
</itemize>
<item>Spares Pool: A  spares  pool can be established on a RaidRunner which provides
 a pool of disks for use by running raid sets which suffer a backend (disk)
 failure. Each disk in the spool may be either hot or warm.  Hot disks are 
 those that  are  immediately  available  i.e spun up. Warm disks are those
 that require spinning-up prior to use.  As different raid sets may use different
 backend (disk) sizes, the spares pool must know the size of each disk in the
 pool. If the RaidRunner has more than one controller, then the usage of a spare
 can be restricted to a specific controller. Given a spare is available to a
 given controller, then the spare is allocated (rconf -repair command based
  on the  following priority - hot spares of the same size on the same rank,
 hot spares of the same size on another rank, warm spares of the same size on
 the same rank, warm spares of the same size on another rank, hot  spares of
 a larger size on the same rank, etc.
<item>The rank is the SCSI ID of the device.
<item>Host Port SCSI ID Assignment: On  each  controller  in a RaidRunner there
 are a number of Host Ports through which data on the RaidRunner is accessed.
 As this host port is effectively a SCSI device then it has to have a SCSI ID
 assigned to it. There are two methods to assign a SCSI ID to a host port. The
 first uses a physical selector  switch  (usually providing  selections  from
  0 to 16) and the second is to internally configure the host port's SCSI ID
 in the non-volatile raid configuration area - the hconf configuration command
 performs this assignment.
<item>SCSI Monitor: On each controller in a RaidRunner one or more Monitors (smon)
 can be set up to run on  a  specified  host port.  This  monitor allows a program
 on a host system to send RaidRunner commands which will be executed in a husky
 subshell as well as transfer of files to and from the  RaidRunner.  This  monitor
  simulates  a  32K &dquot;disk&dquot;  on  a  given SCSI ID (as set up by the
 hconf command or selector switch) and SCSI LUN (which is set up using the mconf
 command).  Execution of commands and file transfers are effected by reading
 from  and  writing to  specific  block  locations on the &dquot;disk&dquot;.
  The reads and writes are to follow a specific protocol based on the block
 locations and order of the reads and writes. See the smon for details of this
 protocol. As different systems use specific blocknumbers for their own internal
 use (eg block number 0 is typically used for  disk labelling) writes to any
 block not used by the protocol are preserved for subsequent reads. Up to 16
 blocks are preserved in the raid configuration area and are re-read by smon
 at boot time so data  is  preserved. If more than 16 blocks are written to,
 then this data is silently discarded. The  block  numbers  used  in the smon
 protocol can be changed to suit different systems which may use the default
 protocol block numbers.

By default, the SCSI monitor will always start at boot time, even if the
 raid configuration area has just been initialized  or is corrupt. RaidRunner
 model specific defaults for the host port, SCSI ID and SCSI LUN for the monitor
 are compiled into the RaidRunner binary. To prevent the scsi monitor from automatically
 executing at boot time the monitor will have to be specifically deleted from
 the controller using the mconf -delete option.
</itemize>
<item>Manual Backend Reconstruction: Raid  types 1, 3 and 5 are resistant to
 a single backend device failure. That is, the raid set's data is still available
 even if one of it's backends fail.  Should a subsequent failure occur on a
  different  backend  then the  raid  set's  data  will  be inaccessible. When
 a backend device does fail, the RaidRunner disengages that device from the
 raid set. To replace a failed backend of a type 1, 3 or 5 raid set, first physically
 correct the failure (eg replace and test the faulty disk), then engage the
 backend in write-only mode and read the entire raid set from the repair entry
 point.  This will result in the reconstruction raid set's data and  parity
  (if  appropriate)  onto  the replaced  backend.   We engage the backend in
 write-only access mode to prevent the raid set from reading from this drive
 during the reconstruction process as data on this backend  is  incomplete.
   Once  we  have  reconstructed  the  data on the replaced backend (i.e the
 read has completed), we then set the backend's access mode to be the access
 mode of the raid set and thus we now have a &dquot;complete&dquot; raid set.
 This reconstruction of data is passive, in that the raid set is still  &dquot;running&dquot;
  during  the  reconstruction, although it will be running slowly.
<item>Automatic Backend Reconstruction: In  the  case of either a type 1, 3 or
 5 raid set, a single backend device failure can result in the automatic replacement
 of the failed backend and subsequent reconstruction of the raid set. This is
 accomplished by specifying a husky script to execute when a backend failure
 occurs - see autorepair. When  a  backend  failure occurs, the backend is disengaged
 from the raid set, and the husky script, if specified, is executed.  The script
 typically allocates a disk from the spares pool, engages it to the raid set
  in write-only  access  mode,  then reads the entire raid set (from the repair
 entry point) which reconstructs the raid set incorporating the new disk. Once
 complete, the disk's access mode is set to the access  mode  of  the raid set.
<item>If,  during  the reconstruction phase (read of whole raid set) the newly
 engaged backend fails, the raid set's data is still available. All the RaidRunner
 will do, is disengage the backend and execute  the  script  again. It  will
  continue to do this until no more spares are available. Alternately, if another
 backend fails during the reconstruction, the raid set will fail.
<item>Configuration Areas: Typically the RaidRunner stores multiple copies of
 the raid configuration area.   Copies  are  stored  on  all disks (in /dev/hd/c.s.l/rconfig)
 that can be written to and in a section of flash ram (/dev/flash/conf) on the
 RaidRunner controller board itself. This is done for redundancy. Whenever the
 raid configuration area is updated, copies are written to each disk (in chip,
 scsi id (rank), lun order) then lastly to flashram. When  the  raid configuration
 is read, it groups, all configuration sources with identical configurations
 then works out the most &dquot;correct&dquot; configuration based on the following
 rules -
<enum>
<item>If all sources are unreadable or corrupt then we used the compiled default
 scsi host id's and scsi monitor configurations.
<item>If all sources are the same (i.e one group) then this is the normal configuration.
<item>If  we  have two groups of configurations, then the group with the highest
 number of identical areas is used. If both groups have the same number of identical
 areas then we pick the group  with  the  highest revision.   If both groups
 have the same number of areas and the same revision, the first group is chosen.
<item>If we have three groups we choose the group with the highest number of
 identical areas. If  two  groups (or all three) meet this criteria we use the
 defined master configuration area - FLASH RAM.
<item>If we have more than three groups, we use the master configuration area
 - FLASH RAM. The  rconf  -check option is used to re-read all configuration
 areas has per the above rules, and if there is differences (more than 1 group)
 it selects the most &dquot;correct&dquot; configuration and re-writes it out
 to all areas. When  the  RaidRunner initially boots it typically only has access
 to the flashram (as the disks have not been bound into the filesystem yet),
 so it uses the configuration stored in  flashram  to  start  (in  a  spun-down
 state) the scsi monitor(s) and scsi target daemons (stargd's). It then binds
 in all disks and executes a rconf -check command and if it had to re-write
 the configuration AND flashram was not in the &dquot;correct&dquot; group it
  may reboot the RaidRunner (as now we can assume than the flashram area is
 now correct).
</enum>

<item>OPTIONS - all commands
<itemize>
<item>-C: This  option checks to see if any significant configuration change
 has been made since boot time to any raid set, host port, scsi monitor or spares
 pool configuration. An appropriate message is printed and a return status (&dollar;status)
 of 1 is returned if a change has occurred, else 0 for no change. Any  modification,
  addition,  deletion  is  considered  to be a significant change.  The only
 NON-significant change is the changing of state of a raid set.
<item>-c: This option checks to see if any significant configuration change has
 been made since boot time to  the relevant  configuration  area  depending
 on the command invoked - rconf - raid sets, hconf - host ports (if not using
 physical selectors), etc. The return status is as per the -C option.
</itemize>
<item>OPTIONS - mconf
<itemize>
<item>Specifying no options is the same as specifying the -list option.
<item>-delete: Delete the scsi monitor given controller number, hostport and
 SCSI LUN.  This option takes  three  values, the controller number, host port
 and the SCSI LUN.  The deletion of a monitor will not take effect until next
 boot of the RaidRunner. 
<item>-list: Print the controller/hostport assigned monitor SCSI LUN.  If the
 optional controller number argument is given then print out the controller,
 hostport and assigned monitor SCSI LUNs for that controller. If a controller
 has no assigned monitor SCSI LUN, then a minus (-) character will be printed
 in place of the SCSI LUN. If an error occurs whilst opening or reading the
 RaidRunner configuration area, a RaidRunner model specific default with be
 listed.
<item>-add: Set  the monitor SCSI LUN on the given controller's host port. This
 option takes three mandatory values and one optional value. The first is the
 controller, the second the host port on  that  controller  and the  last is
 the SCSI LUN to assign the monitor. If the host port has not been assigned
 a SCSI ID, then the monitor will not be executed at boot.  The optional value
 is a comma separated  list  of  nine  (9) numbers which change the default
 block protocol blocknumbers used by the SCSI monitor. See smon for details.
<item>-sml: Print each scsi monitor's stored label information. The information
 is printed as follows - controller number, hostport number, number of stored
 blocks,  followed  by  a  colon,  then  the  block addresses  stored.  Block
  number 0's at the end of this list mean that those available blocks have not
 been written to.
</itemize>
<item>OPTIONS - hconf
<itemize>
<item>Specifying no options is the same as specifying the -list option.
<item>-delete: If the controller does not have a physical SCSI ID selector switch,
 specifying this option will  delete the controller/hostport assigned SCSI ID.
 This option takes two values, the controller number and host- port. By deleting
 an assigned scsi id, no other program (eg scsi monitor or raid  set)  can 
 appear  on this host port.
<item>-list: Print  the controller/hostport assigned SCSI ID.  If the optional
 controller and hostport arguments are given then print out the controller,
 hostport and assigned scsi id for that pair. If no  arguments  are given, 
 then  for each host port on each controller in the RaidRunner, print out the
 controller number, host port and SCSI ID assigned to that host port. If the
 controller does not have host port SCSI ID selector switches, then if a host
 port has not had  a SCSI  ID assigned to it, a minus (-) character will be
 printed in place of the SCSI ID. For example (of a RaidRunner with two controllers
 each of which have two host ports)<tscreen>
<verb>0 0 2
</verb></tscreen>
<verb>0 1 3
</verb>
<verb>1 0 -
</verb>
<verb>1 0 6
</verb>

Which shows that on the first controller (0), the first host port (0) has
 been assigned SCSI ID 2,  the second port (1) has been assigned SCSI ID 3.
  The second controller (1) has NO SCSI ID assigned to it's first host port,
 and SCSI ID 6 assigned to it's port. If an error occurs whilst opening or reading
 the RaidRunner configuration area, a RaidRunner model specific default with
 be listed.

<item>-modify: If the controller does not have a physical SCSI ID selector switch,
 specifying this option will set the SCSI ID on the given controller's host
 port. This option takes three values.  The  first  is  the  controller,  the
 second the host port on that controller and the last is the SCSI ID to assign.
 You cannot set a host port's SCSI ID if any raid set which uses that port is
 active.
</itemize>
<item>OPTIONS - rconf
<itemize>
<item>Any size sub-options (i.e raidsize, cache, iosize, backendsize) can use
 the suffix values. Specifying no options is the same as specifying the -list
 option.
<item>-add: Add a raid set on the RaidRunner. Sub-options are -
<item>-type: Specify the raid type. This option takes values of either 0, 1,
 3 or 5.
<item>-name: Specify the raid name. A name must be alphanumeric, with a maximum
 of 32  characters  and  start with an alphabetic character.
<item>-iomode: Specify  the raid set's io mode. This option takes values of either
 RW, RD or WR for read-write, read-only or write-only respectively.
<item>-size  Specify the raid set's size. This is the size of the raid set in
 512 byte blocks. It must  be  a multiple  of the -iosize value. If it is not
 then it will be automatically adjusted to be so and a message (not error) will
 be printed. In the case of raid type 3 the size must be a multiple of the -iosize
 value multiplied by the number of data backends in the raid set.
<item>-iosize: Specify the raid set's chunksize in bytes. All reads and writes
 on the raid set will be in multiples of this size. When cache is used, this
 is also the size of the cache buffers created (for Raid type 3 the cache buffer
 size is the number of data backends times this value). The RaidRunner establishes
 a maximum number of 512-byte blocks that can be written to at any instant -
 see the write_limit internal variable (internals). Accordingly iosize is limited
 to ensure that at least two of these buffers will fit into this &dquot;writable&dquot;
 portion of cache.
<item>-hostif: Specify the raid set's host interface(s). The host interface is
 the device though which the raid set's  data is externally  accessed. A host
 interface is defined by the quartet - master/slave flag (mflag), controller,
 hostport and scsi lun. Where
<itemize>
<item>mflag: is a target access flag - master(M): full access, slave(S): limited
 access
<item>controller: is the controller on which the raid set is to run
<item>hostport: is the host port a raid set's IO is to be directed
<item>scsilun: is the scsi lun that the raid set propagates out the hostport
</itemize>

The master/slave flag is either M for master, or S for slave mode.  Multiple
 host interfaces are added by repeating this option.

<item>-backendsize: Specify  the  size of the raid set's backends. This is the
 size, in 512 byte blocks, of the raid set's backends. This value is used when
 searching for backends in the spares pool.
<item>-backends: Specify the raid set's backend devices in a comma separated
 list.  A backend device  of  a  raid set  can  be  a  disk or the frontend
 of another raid set. If it is a disk then it will have the format Dc.s.l where
 c is the channel, s is the scsi id (or rank) and l is the scsi  lun  of  the
 disk.  If  it  is a raid set, then it will have the format Rraidsetname where
 raidsetname is the name of the raid set.
<item>-boot: Specify the raid set's boot mode. Values can either be auto or manual
 for autobooting or  manual booting raids. This option is optional and the default
 bootmode is auto. 
<item>-cache: Specify the size, in bytes, of cache that should front-end the
 raid set.  The default size is 0, which means that no cache will be used. The
 cache size must be a  multiple  of  the  raid  set's iosize. 
<item>-stargs: Specify  additional  arguments  to  the stargd process when it
 is created for the given raid set. The arguments are to be enclosed in braces
 - &lcub;&rcub;, IE &lcub;-L 16 -I 512&rcub;
<item>-state: Specify the initial state of the raid set. Values can either be
 active or inactive. This  option is optional and default state is inactive.
<item>-usezoneio: Set  the  zone io usage flag to either on or off. If on, then
 the cache filesystem will fragment write and read requests to suit the zone
 (notch) partitions on the backend disks.
<item>-usespares: Set the spares usage flag to either on or off. If on, then
 a running raid set (1, 3 or 5)  will, on an I/O error, attempt automatic spares
 allocation and reconstruction.
<item>-qlen: Specify the maximum number of io requests that can be queued to
 a backend.  The minimum is 1 and the default is 8.
<item>-delete: Delete a specified raid set from the RaidRunner. The raid set
 must be inactive. 
<item>raidsetname: Specify the name of the raid set to delete.
<item>-list: Print raid set configuration. If a raidsetname name is not specified,
 all raid set  configurations  are printed, one per line in the form (if verbose
 mode is not set (-v) - name type flags size iosize cachesize iomode qlen nhostifs
 hostifs backendsize backends &lsqb;optional backend status&rsqb;. Where the
 flags is a comma separated list from  &dquot;Active&dquot;,  &dquot;Inactive&dquot;,
  &dquot;Used&dquot;,  &dquot;Unused&dquot;,  &dquot;Autoboot&dquot;, &dquot;Manboot&dquot;
  and &dquot;Usespares&dquot;. When a raid set is first flagged to be active,
 then the &dquot;Used&dquot; flag is per- manently set. This knowledge that
 a raid set has been used at some time is used by other  programs  and utilities
 on the RaidRunner. nhostifs is the number of host interfaces to present hostifs
  is  a  comma  separated list of host interface quartets of master/slave flag,
 controller, host port and scsi lun (each separated by a period). For example
 M0.0.4,S0.1.0 means two host  interfaces  - both  on controller 0, one on port
 0 with a scsi LUN of 4 and the other on port 1 with a scsi LUN of 0. The first
 is to be a master target which provides full access by the host, and the second
 is  to  be  a slave which will advise on any host access that the target is
 spun down. The  backends are a comma separated list of backends. If a backend
 has failed then a &dquot;- the spare back-end will also be suffixed. If multiple
 spare backends have been used (i.e the spares failed)  then  each failed backend
 will be suffixed with a (-)<tscreen>
<verb>D0.2.0-,D1s2l0,D2.2.0,D3.2.0,D4.2.0
</verb></tscreen>


means  that  the  backend  D0.2.0  has  failed  and  does  not  have a
 spare and the other backends are
<verb>D1s2l0,D2.2.0,D3.2.0,D4.2.0.
</verb>
<verb>D0.2.0-D5.2.0,D1s2l0,D2.2.0,D3.2.0,D4.2.0
</verb>


means that the backend D0.2.0 has failed and the spare backend, D5.2.0,
 has replaced it and  the  other backends are D1s2l0,D2.2.0,D3.2.0,D4.2.0.
<verb>D0.2.0-D5.2.0-,D1s2l0,D2.2.0,D3.2.0,D4.2.0 
</verb>


means  that  the  backend  D0.2.0 has failed and the spare backend, D5.2.0,
 which replaced it has also failed and the other backends are D1.2.0,D2.2.0,D3.2.0,D4.2.0.

<item>raidsetname: Print the configuration for only the specified raid set.
<item>-modify: This command allows one to change the raid set's state, name,
 bootmode, iomode, host interface,  spares usage,  extra stargd args, cachesize
 or QueueLen. When specifying a state change, then no other modifications are
 allowed. To modify any of the preceding raid set attributes (except state),
  the  raid  set must be inactive. Sub-options are
<item>-name: The name of the raid set to modify
<item>-newname: The new name for the raid set. This new name must still be unique
 amongst the other defined raid sets.
<item>-boot: Change the raid set's boot mode. Values can either be auto or manual
 for autobooting  or  manual booting raids.
<item>-cache: Change the size, in bytes, of cache that should front-end the raid.
<item>-hostif: Change  the raid set's host interface(s). The host interface is
 the device though which the raid set's data is externally accessed. A host
 interface is defined by  the  quartet  -  master/slave flag (mflag), controller,
 hostport and scsi lun. Where mflag is  a target access flag - master(M): full
 access,  slave(S): limited access controller is the controller on which the
 raid set is to run hostport is the host port  a  raid  set's IO is to be directed
 scsilun is the scsi lun that the raid set propagates out the hostport The master/slave
 flag is either M for master, or S for slave mode.  Multiple host interfaces
 are added  by  repeating  this option. Note you must specify all host interfaces
 required in the one command. Thus to delete a host interface you modify without
 that host interface option. 
<item>-iomode: Change the raid set's io mode. This option takes values of either
 RW, RD or WR  for  read-write, read-only or write-only respectively.
<item>-qlen: Change the maximum number of io requests that can be queued to a
 backend.
<item>-stargs: Specify  additional  arguments  to  the stargd process when it
 is created for the given raid set. The arguments are to be enclosed in braces
 - &lcub;&rcub;, IE &lcub;-L 16 -I 512&rcub;
<item>-state: Change state of the raid set. Values can either be active or inactive.
<item>-usespares: Set the spares usage flag to either on or off.
<item>-rebuild: The rebuild option is used when a stored raid set configuration
 has been corrupted and  that  raid  set had faulty backends optionally supplemented
 with spares. Normally, if the stored raid set configuration was corrupted in
 some way and it did not have any faulty drives then one would just delete the
 raid set and then add it. If any of the backends were faulty then we  need
  to  store this information in the newly re-created raid set configuration.
 The rebuild option does this. If the faulty backend did not use any spares,
 then the -rebuild option  will  just  mark  that  backend faulty.  If  it 
 did use spares, then repeated invocations of this command (with the -spare
 sub-option) will add spares as appropriate, marking the backend faulty and
 any previously configured spares  faulty also.  The  last invocation with the
 -spare sub-option will add the spare as in use but not faulty.  If the last
 spare was also faulty, then a final invocation without the -spare sub-option
  will  mark  that last spare faulty.
<item>-name: The name of the raid set.
<item>-drive: Specify  the  backend  to  rebuild. The backend specification takes
 the form of the index of the backend in the list of backends. The first backend
 in a raid set has the index 0.
<item>-spar:e Optionally specify the spare device which is to be  configured
  onto  a  backend.   This  device should already be in the spares pool and
 be unused. If  no  spares  have  been  assigned to the backend, then the backend
 is marked faulty and the spare is added and marked as in use. If spares have
 been assigned to the backend, then the last spare is  marked faulty and the
 additional spare is added and marked as in use.
<item>-mkfaulty: The mkfaulty option is used to mark a particular backend as
 faulty.  When a backend of a raid set which does not use spares fails, we need
 to update the RaidRunner configuration of this fact. This command's sub-options
 are the same (and have the same effect) as the rebuild command's sub-options
 excluding the -spare sub-option.
<item>-repair: Reconfigure  a  raid set to replace a backend with a spare backend
 allocated from the spares pool. When the -action option is start then the depth
 of the new spare and the spare device name is printed. The depth  is  the 
 number of spares allocated to that backend. When the first spare is allocated,
 then the depth will be 1. When the second is allocated then the depth is 2
 and so on. The  depth  is  used  when re-engaging  a spare which has just been
 reconstructed. If the depth is different after the reconstruction has occurred
 then we know that the spare has failed and another spare has  been  allocated
  so  we   wont attempt the re-engage.
<item>-name  The name of the raid set.
<item>-drive Specify  the  backend  to  replace. The backend specification takes
 the form of the index of the backend in the list of backends. The first backend
 in a raid set has the index 0.
<item>-action: Specify the repair action. Values are either start or finished.
  Normally, when a spare is allocated,  the next steps are to reconstruct the
 data on that spare then re-engage the spare.  If a failure occurs on the spare
 during reconstruction, then the  spare  should  not  be  re-engaged. Thus,
  a  raid  set  should know that a reconstruction is in process. Once the reconstruction
 is complete then the reconstruction knowledge is cleared. The start value will
 print out the  depth of  the  newly allocated spare and the spare's device
 name.  If no spares are available an error will be printed and the depth of
 the last spare for the backend will be printed only.  The  finished action
 checks the current depth of spares against a given depth and clears the reconstruction
 flag if the depth is the same (that is, the spare reconstructed correctly).
<item>-depth: Specify the depth of the spare device when performing a finished
 action.  A  check  is  made  to ensure  the  current  depth  of  the  backend
 is the same is the specified one. This essentially checks to see if another
 spare has been allocated on this backend during the reconstruction.
<item>-replace: This command is used when we have physically repaired (or replaced)
 the original failed backend and  we wish  to re-integrate it back into the
 raid set. This is done by deallocating the current running spare and reconstructing
 the raid on the replaced original backend.  This command is similar to  the
  -repair: command  except  that the working spare is deallocated from the backend
 and returned to the spares pool PRIOR to the reconstruction. This way, if the
 newly replaced drive fails, we have a  spare  to  reallocate.
<item>-name: The name of the raid set.
<item>-backend: The name of the backend device that is being re-integrated.
<item>-action: Specify  the  replacement action. Values are either start or finished.
  When the start action is specified, the last spare on the backend is returned
 to the spares pool if it is  in  a  working state.  Then the current depth
 of spares on the backend and the backend's index into the last of backends
 (the raid set's drive number) is printed out.  If a failure occurs on the backend
  during reconstruction, then the backend should not be re-engaged. Thus, a
 raid set should know that a reconstruction is in process. Once the reconstruction
  is  complete  then  the  reconstruction knowledge  is  cleared. The finished
 action checks the current depth of spares against the given depth and clears
 the reconstruction flag if the depth is the same (that  is,  the  spare  reconstructed
  correctly) and then releases any spares back to the spares pool (all these
 spares will be faulty). If the depth is different then the reconstruction has
 failed and an error message is printed  and the spares are left alone.  -depth
 Specify the depth of the spare devices when per- forming a finished action.
 A check is made to ensure the current depth of spares of the  backend is  the
  same is the specified one. This essentially checks to see if a spare has been
 allocated on this backend during the reconstruction.
<item>-unrepair: Typically, when we repair a raid set using spares, we modify
 the raid set's configuration  to  indicate the faulty drive, the allocation
 of a spare and it's state of &dquot;under construction&dquot;. We then perform
 the reconstruction, and on success we re-modify the configuration to clear
 the &dquot;under construction&dquot;  state. IE a sequence of commands like
 -<tscreen>
<verb>rconf -repair .. -action start ...
</verb></tscreen>


rebuild the raid set
<verb>rconf -repair .. -action finish ... 
</verb>


Now, if the spare we allocated is faulty or the reconstruction fails, we
 need to turn off the &dquot;under construction&dquot; state, deallocate the
 spare and re-mark the original failing drive as faulty (as well  as the  spare
  drive  if  it  was  faulty). The -unrepair option does this. The options are
 similar to the

<item>-repair: options with the addition of the name of the originally faulty
 backend.
<item>-name: The name of the raid set.
<item>-drive: Specify the backend to unrepair. The backend specification takes
 the form of the  index  of  the backend in the list of backends. The first
 backend in a raid set has the index 0.
<item>-backend: The name of the backend device that is being un-repaired.
<item>-depth: Specify  the  depth of the spare device as allocated in the original
 rconf -repair -action start command.  This essentially checks to see if another
 spare has been  allocated  on  this  backend during the failed reconstruction
 or spare testing.
<item>-init: Initialize  the  RaidRunner  configuration area. With this option
 all raid set, host port, scsi monitor and spares spool configurations are initialized.
  The GLOBAL environment variables,  and  scsi  monitor (smon)  data  blocks
  which  are  located  in the Raid configuration area, will NOT be deleted.
  To enable at least one scsi monitor to come up, the scsi monitor lun and it's
 associated host port scsi id is initialized to a RaidRunner model specific
 default. Use this option with caution.
<item>-fullinit: Initialize  the  RaidRunner  configuration  area.  This  option
 performs the same function as the -init option and additionally clears all
 GLOBAL environment variables and the scsi  monitor  (smon)  data blocks.
<item>-check: Cause  the multiple configuration areas to be all re-read and,
 if different, re-written as per the raid configuration area multiple source
 rules.  If more than one raid configuration area differs to the others AND
 the &dquot;correct&dquot; area does not include flashram, then rconf returns
 a non-zero exit status, if all areas are the same or all areas are unreadable
 (or corrupt) then rconf returns a zero exit status.
<item>-validate: Perform a consistency check on the current raid sets, spares
 etc and print out any inconsistencies.  If any  inconsistencies  occur  messages
  will  be printed and the return status of rconf will be 1. If no inconsistencies
 are present, then nothing will be printed and the return status will be NULL.
<item>-size: Print the number of bytes actually used in the raid configuration
 store.
<item>-syslog: Print any syslog entries stored in the configuration area. Notes
 that these entries will be deleted  on an rconf -init or -fullinit.
<item>-maxiochunk: Search  through  all raid sets currently configured and print,
 in 512-byte blocks, the maximum IO Chunk size of all raid sets.
<item>-v: Set the verbose option. This option only effects the listing of Raid
 Sets. It prints additional  detail when listing the Raid Sets.

</itemize>

<item>OPTIONS - spool

Specifying no options is the same as specifying the -list option.
<itemize>
<item>-add: Add a disk to the spares pool of the RaidRunner. Sub-options are
 -
<item>-name  the  name  of  the  disk.  If the disk is already used by a raid
 set or is already in the spares pool, an error will be printed.
<item>-backendsize: the size (in 512 byte blocks) of the added disk. This value
 can be in the form specified by suffix.
<item>-type: the type of the spare. Spare devices can either be hot (spun up)
 or warm (spun down).
<item>-delete: delete the specified spare from the spares pool. A check is made
 to see that the spare is not in use.
<item>-list: Print out the current state of each spare in the pool. The format
 is 
<verb>Backend BackendSize hot|warm controller_no|Any Used|Unused Faulty|Working
 comments
</verb>
<item>Configuration Corruption: Under  certain conditions, it is necessary to
 corrupt the RaidRunner configuration area. An example of this is a RaidRunner
 that has been configured in such a way that all memory is consumed and the
 RaidRunner  will not respond to any commands either on the console or via the
 scsi monitor.  Given there is not enough memory to delete raid sets or even
 execute the reboot process (or any other for that matter), then a command which
 corrupts  all  the  RaidRunner configuration areas (and hence will prevent
 the automatic creation of raid sets at reboot - i.e the consumer of memory)
 and then immediately reboot's without using  any  additional  memory  will
 allow  the  user to reconfigure the RaidRunner when it has re-booted. The corrupt-config
 command performs this task.
</itemize>

<item>RETURN VALUES: If an error occurs, the &dollar;status environment variable
 is set to 1, else null.  When  the  configuration  change options  (-C  or
 -c) are given, the return value (&dollar;status) will be 1 if a configuration
 has changed since boot else 0.
<item>BUGS: Currently, if you duplicate sub-options within a command, the last
 occurrence will be the value set. For example if the command rconf -modify
 -name F -newname B -newname C -cache 1M -cache 2M is executed then the newname
 will be &dquot;C&dquot; and the cache size set to 2M (2 megabytes).
<item>SEE ALSO: husky, autorepair, replace, suffix, setenv, unsetenv, printenv,
 smon
</itemize>

<sect1>REBOOT - exit K9 on target hardware + return to monitor
<p>
<itemize>
<item>SYNOPSIS: reboot &lsqb;-i&rsqb; &lsqb;-s&rsqb; rboot &lsqb;-i&rsqb; &lsqb;-s&rsqb;
 rbootimed
<item>DESCRIPTION: reboot abruptly leaves the K9 kernel (on target hardware)
 and either re-enters the underlying hardware monitor or re-initializes the
 K9 kernel. Aside from flushing the write cache and initialising the battery
 backed-up ram no cleanup is performed on K9 processes (no signals, no  nothing).
 If  no  options  are  given  then the reboot will NOT do any memory tests prior
 re-initialising the K9 kernel. 

If the -s option is given then  memory tests
 will be performed prior to re-initialising the K9 kernel.  During these memory
 tests, a spinning - is  displayed  on  the  RaidRunner's console.  This  indicates
  the memory test is executing. If you press the space key during this test,
  then  you  will  drop  into  the  underlying RaidRunner monitor. If the -i
 option is given then all I/O to the back-end drives will inhibited.  That is,
  no spun-down drives will be started and no attempt to flush the cache is performed.
 

rboot is an alias for reboot.

rbootimed provides a special entry-point into
 the reboot process and is equivalent to calling reboot with the -i option.
 Unlike reboot, which is executed as a sub-process, rbootimed is interpreted
 via husky and immediately commences the reboot process and hence does not use
 any extra memory. This is useful when the RaidRunner has run out of memory
 and you need to reboot the RaidRunner into single user state. 

On simulation
 platforms such as Unix this command is not implemented (but typically the Unix
 &dquot;interrupt&dquot; signal has the similar effect of killing the Unix process
 containing the K9 simulation).
</itemize>
<sect1>REBUILD - raid set reconstruction utility
<p>
<itemize>
<item>SYNOPSIS:
<itemize>
<item>rebuild -d file -s size -b bufsize -D dno -R rname -n nbends -r rtype &lsqb;-p
 pri&rsqb; &lsqb;-v&rsqb; &lsqb;-S sleep_period&rsqb;
<item>rebuild -d file -l &lsqb;-v&rsqb;
<item>rebuild -L &lsqb;-v&rsqb;
</itemize>
<item>DESCRIPTION: To  reconstruct data onto a newly incorporated drive in a
 raid set, the raid set's repair entry point is to be completely read. Additionally
 the read must be in multiples of the raid set's bufsize and the last  read
  must align to the end of the raid set (i.e cannot attempt to read past the
 end of the raid set). The rebuild utility performs this reconstruction. When
 rebuild starts, it allocates an internal buffer whose size is maximized to
 the available memory and which is a multiple of the given buffer size.  The
 raid set's repair entry point is read via these large buffers and the last
 read is guaranteed to align to the end of the raid set. As rebuild reads from
 the raid set's repair entry point, a check is made to see if the backend that
  is  being rebuilt  is  still  engaged  to the raid set, and if the backend
 has failed (disengaged from raid set) rebuild prints a message and returns
 an exit status of 2. If the raid set fails during reconstruction (a second
 backend fails) then rebuild prints a message and returns an exit status of
 1.

Rebuilds, by default, consume large amounts of RaidRunner resources which
 would result in a large reduction in RaidRunner I/O throughput (to the host).
 A priority can be given to the rebuild program to reduce this  demand on  resources.
 This priority ranges between 0 (use minimal resources) and 9 (use maximum resources
 available). Naturally by specifying a low priority, the time to complete a
 rebuild will increase. The current state of any completed or &dquot;in-progress&dquot;
 rebuild is recorded for informative  uses.  Up  to  10  of these  records 
 are  kept  at  any  one  time.   If a new rebuild is requested and we have
 already used all 10 records, we find the first &dquot;inactive&dquot; (or completed)
 record and re-use that one. If all 10  records  are  currently  marked &dquot;active&dquot;
 (which means that we currently have 10 rebuilds currently in progress), then
 no record of the new rebuild will be kept. These records are initialized at
 boot time.
</itemize>
<itemize>
<item>OPTIONS
<itemize>
<item>-d file: Specify the file to read.  This is typically the repair entry
 point of the raid set.
<item>-s size: Specify the raid set's size, in 512-byte blocks.
<item>-b bufsize: Specify the raid set's IO chunksize - bufsize, in 512-byte
 blocks. In the case of a raid type  3,  this should be the number of data drives
 times the size of the IO chunksize.
<item>-n nbends: Specify  the number of backends in the raid set. This is needed
 along with the bufsize option to ensure that the raid set's repair device is
 read in multiples of the raid set's stripe size.
<item>-D dno: Specify the backend index (within the raid set) that is being rebuilt.
<item>-R rname: Specify the name of the raid set that is being rebuilt. Specify
 the raid type of the raid set being rebuilt. Must be 1, 3 or 5.
<item>-p pri: Specify a priority at which the rebuild is to be run at. The priority,
 pri, must be a number between  0 (lowest) and 9 (highest).  When rebuild is
 executed by automatic or manual scripts an environment vari- able, RebuildPri,
 is checked to see what priority a raid set should be re-built. If  this  variable
  is not set, then the default priority is 5.  See environ for details.
<item>-S sleep_period: Specify  a  number of milliseconds to sleep between each
 reconstruct access of the raidset. The period, sleep_period, must be a number
 between 0 (no sleep) and 60000 (60 seconds).  When rebuild  is  executed by
 automatic or manual scripts an environment variable, RebuildPri, is checked
 to see what sleep period a raid set should use. If this variable is not set,
 then the default period for the given  priority  is used.  See environ for
 details.
<item>-v: Set verbose mode. When rebuilding, if verbose mode is set, the current
 number of reads and total expected number of reads is printed for every 10
 percent of the reconstruction completed. When printing the state a specific
 or all rebuilds, verbose mode will produce a  long  listing  of  the rebuild
 status.
<item>-l: Print the current state of the specified rebuilding (-d) file.
<itemize>
<item>By default the following colon separated fields are printed
<item>the rebuild file (entry point to raid set repair device)
<item>the size of the file (raid set) in 512 byte blocks
<item>the IO chunksize of the file (raid set) in 512 byte blocks
<item>the size of the buffer (in 512 byte blocks) being used for reading
<item>the total number of reads needed to read the whole file
<item>the current number of reads performed so far,
<item>the priority of the rebuild 
<item>the number of milliseconds between each access to sleep 
<item>the state of the rebuild - either &dquot;active&dquot; or &dquot;complete&dquot;
 the  error  message  that  this rebuild failed on - set to &dquot;none&dquot;
 if the rebuild successfully completed. 
</itemize>

When verbose mode (-v) is set, the above is printed with appropriate labels.

<item>-L: Print the rebuild status of ALL rebuilds in progress or completed (in
 the  same  form  as  for  the  -l option).
</itemize>

<item>PRIORITY: The  speed  at  which  a  rebuild  occurs  and  impact it has
 on the system is determined by the priority and  optional sleep period between
 accesses.  When rebuild allocates the buffer to use it will limit this  buffer's
 size  to  the  maximum available contiguous memory segment or 2 Megabytes which
 ever is the lessor. The memory will then be scaled by pri + 1 / 10. That is,
 if you specify a priority of 0 then the buffer will be one tenth of  the maximum
 buffer siz, if you specify a priority of 4 then it will be half. This resultant
 buffer size is then trimmed to ensure it is a multiple of a raid set's stripe
 size. Between each read/write access of the raid set's repair device, rebuild
 may sleep for a given period  of  milliseconds  to  reduce the overhead of
 the rebuild process. This sleep period may be given on the command line. If,
 not then the priority value is used to work out the period. The table below
 specifies what period is associated with which priority.
<itemize>
<item>0: 2000 milliseconds (2.00 seconds)
<item>1: 1750 milliseconds (1.75 seconds)
<item>2: 1500 milliseconds (1.50 seconds)
<item>3: 1250 milliseconds (1.25 seconds)
<item>4: 1000 milliseconds (1.00 seconds)
<item>5: 750 milliseconds (0.75 seconds)
<item>6: 500 milliseconds (0.50 seconds)
<item>7: 250 milliseconds (0.25 seconds)
<item>8: 100 milliseconds (0.10 seconds)
<item>9: 0 milliseconds (no sleep)
</itemize>
<item>EXIT STATUS

The following exit values are returned:
<item>0: Successful completion.
<item>1: The raid set failed reconstruction. This means that the raid set has
 failed.
<item>2: The raid set's backend that is being rebuilt has failed. This means
 that the raid set is still valid.
</itemize>
<itemize>
<item>SEE ALSO: raid1, raid3, raid5, repair, replace, environ
</itemize>
<sect1>REPAIR - script to allocate a spare to a raid set's failed backend
<p>
<itemize>
<item>SYNOPSIS: repair raidsetname backend
<item>DESCRIPTION: repair  is  a  husky script which is used to allocate a spare
 drive to a failed backend of a raid set. This is typically done when a raid
 set has a failed backend and no spares were available at the time  of  failure
  and now you want to allocate the spare (as opposed to fixing the failed backend).
 After  parsing  it's  arguments  repair get's a spare backend (of appropriate
 type) from the spares pool.  The spare drive is then engaged in write-only
 access mode in the raid set and a reconstruct  of  the  raid  occurs (read
  of  the  whole  raid set).  This read is from the raid file system repair
 entrypoint. Reading from this entrypoint causes a read of a block immediately
 followed by a write of that block. The read/write sequence  is atomic  (i.e
  is not interruptible).  On successful completion of the reconstruction, the
 spare is then engaged in the correct iomode for the raid set.  The process
 that reads the repair entrypoint is rebuild.

This device reconstruction will take anywhere from 10 minutes to one and
 a half hours depending  on  both  the size and speed of the backends and the
 amount of activity the host is generating. During  device reconstruction, pairs
 of numbers will be printed indicating each 10&percnt; of data reconstructed.
 The pairs of numbers are separated by a slash character, the first number being
 the number of blocks reconstructed so far and the second being the number
 of blocks to be reconstructed.  Further status about the rebuild can be gained
 from running rebuild. Checks are made to ensure that the raid set is running,
 the spare works, and that there is no failure  of  the spare during reconstruction.
</itemize>
<itemize>
<item>OPTIONS
<itemize>
<item>raidsetname: The name of the raid set.
<item>backend: The name of the failed backend which is being replaced by a spare.
</itemize>
<item>SEE ALSO: rconf, rebuild
</itemize>
<sect1>REPLACE - script to restore a backend in a raid set
<p>
<itemize>
<item>SYNOPSIS: replace raidsetname backend
<item>DESCRIPTION: replace  is a husky script which is used to reconfigure back
 in a physically repaired backend of a type 3 or 5 raid set. After parsing it's
 arguments replace does a quick read/write test of the  specified  backend 
 to  ensure  it's working.   If  a  working  spare is currently running in place
 of the backend, it disengages it and returns it back to the spares pool. The
 backend drive is then engaged in write-only access mode in the  raid  set 
 and  a reconstruct  of  the  raid occurs (read of the whole raid set).  This
 read is from the raid file system repair entrypoint. Reading from this entrypoint
 causes a read of a block immediately followed  by  a  write  of  that block.
  The  read/write  sequence is atomic (i.e is not interruptible).  On successful
 completion of the reconstruction, the backend is then engaged in the correct
 iomode for the raid set and any other faulty spare backends  that  were  associated
  with  that  backend are returned to the spares pool.  The process that reads
 the repair entrypoint is rebuild. This device reconstruction will take anywhere
 from 10 minutes to one and a half hours depending  on  both  the size and speed
 of the backends and the amount of activity the host is generating. During 
 device reconstruction, pairs of numbers will be printed indicating each 10&percnt;
 of data reconstructed. The pairs of numbers are separated by a slash character,
 the first number being the number of blocks reconstructed so far and the second
 being the number of blocks to be reconstructed.  Further status about
 the rebuild can be gained from running rebuild. Checks are made to ensure that
 the raid set is running, the backend works, and that there is no failure of
 the backend during reconstruction.
<item>OPTIONS
<itemize>
<item>raidsetname: The name of the raid set.
<item>backend: The name of the backend which is being restored.
</itemize>
<item>SEE ALSO: rconf, rebuild
</itemize>
<sect1>RM - remove the file (or files)
<p>
<itemize>
<item>SYNOPSIS: rm &lsqb;-f&rsqb; &lsqb; file ... &rsqb;
<item>DESCRIPTION: rm  remove  the named file (or files). &lsqb;A directory is
 considered to be a file.&rsqb; If all the given files can be removed then NIL
 (i.e. true) is returned as the  status;  otherwise  the first file name that
 could not be removed is returned (and this command will continue trying to
 remove files until the list is exhausted). 

If  the  -f  option  is  given,
  then files that could not be removed are ignored and NIL (i.e. true) is returned
 as the status.
<item>BUGS: The use of rm on non-empty directories orphans those child files.
</itemize>


<sect1>RMON - Power-On Diagnostics and Bootstrap
<p>
<itemize>
<item>SYNOPSIS<tscreen>
<verb>v1.0
</verb></tscreen>
<verb>DRAM: 010 Mb
</verb>
<verb>Batt: B0000008-B007FFFC
</verb>
<verb>PWROK 1:BAD 2:OK
</verb>
<verb>0:720seE 1:720seE 2:720seE 3:720seE 4:720seE 5:720seE 6:770B 7:770B
</verb>
<verb>S/N: ABC-12345 B
</verb>
<verb>-
</verb>

<item>DESCRIPTION: rmon will normally perform a power-on diagnostics and then
 bootstrap the main raid code. By typing a space before the count-down has finished
 rmon will abort the power-on diagnostics and prompt for  a  command  to  be
 entered from the console serial port.

The first line printed by rmon is it's version number.  The second line
 is the size (in hexa-decimal) of DRAM. The next line indicates the type and
 usage of Battery-Backup SRAM found.  This can be a variety of values  and if
  there  are  two hexa-decimal values printed,  this is then the range of inclusive
 addresses upon which the power-on diagnostics will test Battery Backed-up SRAM.
  If there is only one value this indicates the size  of Battery Backed-up SRAM,
  but no power-on diagnostics will performed upon it.  All possible values are
 :-
<verb>         Batt: 00000000          No Battery Backed-up SRAM present.
</verb>
<verb> 
</verb>
<verb>         Batt: B0000000-B007FFFC 512Kb SRAM, B0000004==0 (No data).
</verb>
<verb>         Batt: B0000008-B007FFFC 512Kb SRAM, B0000004==1 (No data).
</verb>
<verb>         Batt: B00XXXXX-B007FFFC 512Kb SRAM, B0000004==2 (Saved data,
</verb>
<verb>                                 B0000000==B00XXXXX, where B00XXXXX is
</verb>
<verb>                                 start of unused data).
</verb>
<verb>         Batt: B0080000          512Kb SRAM present, but the contents of
</verb>
<verb>                                 SRAM is not one of the above, or could
</verb>
<verb>                                 be B0000004==2 and B0000000==B0080000.
</verb>
<verb>                                 No pon testing done on it.
</verb>
<verb> 
</verb>
<verb>         Batt: B0000000-B03FFFFC 4Mb SRAM, B0000004==0 (No data).
</verb>
<verb>         Batt: B0000008-B03FFFFC 4Mb SRAM, B0000004==1 (No data).
</verb>
<verb>         Batt: B0XXXXXX-B03FFFFC 4Mb SRAM, B0000004==2 (Saved data,
</verb>
<verb>                                 B0000000==B0XXXXXX, where B0XXXXXX is
</verb>
<verb>                                 start of unused data).
</verb>
<verb>         Batt: B0400000          4Mb SRAM present, but the contents of
</verb>
<verb>                                 SRAM is not one of the above, or could
</verb>
<verb>                                 be B0000004==2 and B0000000==B0400000.
</verb>
<verb>                                 No pon testing done on it.
</verb>


Note  the case where location B0000004 has a value of 2 (Saved data present),
 but where B0000000 (the start of unused data) points to a word address just
 past the last byte of Battery Backed-up  SRAM.   This  latter  case will  cause
 a single value (say B0080000, for 512Kb Battery Backed-up SRAM) to be printed.
  This case does not indicate that any contents of Battery Backed-up SRAM is
 deemed incorrect,  but that Battery Backed-up  SRAM is full of data and that
 no power-on diagnostics will be performed upon Battery Backed-up SRAM.


The DRAM memory sizing algorithm will cater for between 8Mb and 256Mb of
 DRAM,  and there need be only 30 bits out of 32 bits words in each DRAM set
 that need work properly, for the sizing to function properly.  The  DRAM consists
 of two banks of memory,  A and B,  each of two slots.  When using a bank of
 memory both slots of that bank must be occupied with a Simm of the same type
 and size.  If only one bank is to be used,  then it must be Bank A. The  type
 of Simm memory may be single or double sided.  Placing two double sided Simms
 (which,  as mentioned above must be both the same size) into Bank A is equivalent
 to populating all four slots with single sided Simms of a size that is exactly
 one half of the double sided Simms size.  The Bank B in such a case cannot
 contain any Simms. Each bank can potentially be using single sided Simms  of
  different  sizes,  but  the first bank must have the larger sized Simms.
<verb>            DRAM Size DRAM last address
</verb>
<verb>            Hex Dec   Cached    Uncached
</verb>
<verb>            008  8    7FFFFF    A07FFFFF
</verb>
<verb>            010  16   FFFFFF    A0FFFFFF
</verb>
<verb>            020  32   1FFFFFF   A1FFFFFF
</verb>
<verb>            040  64   3FFFFFF   A3FFFFFF
</verb>
<verb>            080  128  7FFFFFF   A7FFFFFF
</verb>
<verb>            100  256  FFFFFFF   AFFFFFFF
</verb>


On  the  fourth  line  is  the power supply status.  This will be one of
 two variations.  The first for single power supply systems,  the power supply
 summary status is printed at PWROK (for good) or PFAIL if this is  not good.
 The  second  is for multi-power supply systems,  the summary status will be
 followed by the individual status of each power supply.  A PFAIL will be printed
 if any of the power supplies are faulty.  At this  point on  non-pseudo-static
 DRAM systems the monitor will hang if the summary status is PFAIL.  A pseudo-static
 DRAM system will never print this line or any of the preceding lines (i.e.
  version  line,  DRAM  size  or  Battery Backed-up SRAM size) and always immediately
 hang.


On  the  fifth line is summary of the SCSI chips used in the system.  Each
 item in this report consists of the index No. for that chip (from 0 to 7),
 followed by a ':' then a string of text  indicating  the  model.   This model
 consisting of it's chip type and revision level.  A summary of the known part
 No.s vs the model is :-
<verb>                                  Bits 7 to 4 of
</verb>
<verb>             Model    Part No.    MACNTL CTEST3
</verb>
<verb>              720B   609-0391071   0000   0001
</verb>
<verb>              720C   609-0391324   0000   0010
</verb>
<verb>              720E   609-0391955   0000   0100
</verb>
<verb>            720seE   609-0391949   0001   0100
</verb>
<verb>              770A   609-0392179   0010   0000
</verb>
<verb>              770B   609-0392393   0010   0001
</verb>


There  maybe a sixth indicating the serial number of the unit.  If the
 last 12 bytes of the FlashRam boot partition is left in an unblown state (all
 ones),  then this line will not be appear.  Otherwise  these  last  12 bytes
  will be printed.  These 12 bytes may include trailing blanks.  The four bytes
 of FlashRam preceding the serial no. contain 26 bits representing the revision
 level of the board.  If any of these bits are cleared and there is a serial
 no. present then the revision level from A to Z will be printed.


After  printing  the  above  configuration information,  the DRAM and Battery
 Backed-up SRAM (if any found), will have a Knaizuk-Hartmann memory test performed
 upon them.  This memory test does  a  quick non-exhaustive check  for  stuck-at
 faults in both the address lines as well as the data locations.  This test
 is disabled on the following conditions :-
<item>If the upper 17 bits of first location,  contain the hex bit pattern 0x3C1A0000
 and  there  are  no  parity errors on thence reading all of the rest of DRAM.
  Such a condition will result in the code starting at the first location to
 subsequently executed.
<item>If no DRAM is found.  The monitor will not autoboot the main raid code,
 but print a monitor prompt and wait for a monitor command (see below).


By typing a space,  any memory tests that may have been started will be
 aborted.  The monitor will print a prompt and wait for a monitor command (see
 below).


All other conditions will result in the main raid code to be read from
 FlashRam and started.  Whilst the  memory test is in progress a sequence of
 -, /, | and  characters are printed on the console giving the appearance of
 a rotating bar.  On-board LED 1 will be flashed every 10ms and LED 2 will change
 state between  each  phase of the test.  As noted above these tests can be
 abort by typing a space on the console. When  rmon is in command mode a variety
 of commands may be issued.  These mostly relate to various diagnostics that
 can be performed,  or to how flash RAM may be upgraded with new firmware.


<item>GENERAL COMMANDS: All values and addresses used in the monitor are to be
 in hexadecimal.  Commands must start at  the  beginning of  a  line and are
 case sensitive.  Commands must be separated by semi-colons ';' or a newline.
  If a command syntax error occurs, then that command's usage line will be printed.
  If a command (e.g.  command_name)  is  not recognized, the message unknown
 command: command_name will be printed.

Note  that  any  command that attempts to modify regions of memory that
 are occupied by the monitor will cause unpredictable results.  Currently the
 monitor uses locations from CPU addresses 801E0000  to  801FFFFF  inclusive.
<item>?: This command, will print out a summary of the more generally useful
 commands available in the monitor.
<item>&lcub; some comment &rcub;: will ignore all text from the leading open-brace
 to the first closing - brace.  This allows you to comment  your  monitor  scripts
 (set of monitor commands) prior to downloading.  Please NOTE that comments
 cannot be nested, that is there can only be one opening-brace and closing-brace
 on a line.
<item>* count commands ...: will repeat all commands up to the newline count
 times.
<item>( commands ): will execute the sequence of commands from the opening parentheses
 to the closing parentheses (or  new- line)  as  though they were on a line
 by themselves.  For example to nest repeat (*) commands one could enter the
 line<tscreen>
<verb>* 20 (* 8 pb 5F 0); (* 10 pb 6F 1)
</verb></tscreen>


which will put the byte 0 into memory location 5F eight times, then put
 the byte 1 into memory location 6F  ten  times,  and  repeat both these put
 byte commands 20 times.  Thus the location 5F will have the byte value 0 written
 into it a total of 160 times and the location 6F will have the byte value 1
  writ- ten into it a total of 200 times.
<itemize>
<item>b: The command will boot the main raid code.
<item>ba: The command will auto-boot the main raid code,  as if from power up.
<item>g &lt;address&gt;: Go to (jump to) a code address and start execution at
 that address.
<item>l: Download a program or data over the serial port. The data is expected
 in Motorola Packed S format. If an error occurs during download then the message
 Unrecoverable error in S-format loader.
<item>lg: Download  a  program  over  the serial port and commence execution
 of the program.  The program data is expected in Motorola Packed S format.
 After the data or program has been downloaded successfully,  then commence
 execution at the load address (specified within the downloaded file). If an
 error occurs during download then the message &dquot;Unrecoverable error in
 S-format loader&dquot;. will be printed and the program will not be executed.
</itemize>

<item>MEMORY COMMANDS: The  following  commands  are used to display, change
 or test memory.  Most of these commands have three forms depending on the size
 of memory access.  These forms are - a byte form (8-bit), a short word form
 (16-bit) and long  word  form  (32-bit).  When  using  the  short  or long
 word form, any addresses used must be short word (16-bit) or long word (32-bit)
 aligned.  If an unaligned address is given, the error message<tscreen>
<verb>cmd: bad address alignment 
</verb></tscreen>


<itemize>
is printed. To differentiate between the three forms of memory access,
 the suffixes b, w and l  are  used  for byte, short word and long word respectively.
<item>db|dw|dl start_address &lsqb;end_address&rsqb;: These  commands  display
  the  contents of the specified memory location or memory range. Memory can
 be displayed in byte, short word or long word sizes using the db, dw and dl
 commands respectively.  If  no ending address is given, then only the contents
 of the first address is displayed. Each line of output from these commands
 have the format: address: contents contents .... contents. Where up to 16 bytes
 are printed on each line. For example
<verb>&lcub;rmon&rcub; db 60 7F
</verb>
<verb>00000060: A0 9F 9E 9D 9C 9B 9A 99 98 97 96 95 94 93 92 91
</verb>
<verb>00000070: 90 8F 8E 8D 8C 8B 8A 89 88 87 86 85 84 83 82 81
</verb>
<verb>&lcub;rmon&rcub; dw 60 7F
</verb>
<verb>00000060: FFA0 FF9E FF9C FF9A FF98 FF96 FF94 FF92
</verb>
<verb>00000070: FF90 FF8E FF8C FF8A FF88 FF86 FF84 FF82
</verb>
<verb>&lcub;rmon&rcub; dl 60 7F
</verb>
<verb>00000060: FFFFFFA0 FFFFFF9C FFFFFF98 FFFFFF94
</verb>
<verb>00000070: FFFFFF90 FFFFFF8C FFFFFF88 FFFFFF84
</verb>
<item>pb|pw|pl address value ....: These  commands  put the given value(s) into
 the specified memory location.  Memory can be addressed in byte, short word
 or long word sizes using the pb, pw and pl commands respectively.  If  more
  than  one value  is  given, then the first value is put into the specified
 memory location, the next value is put into the next aligned memory location,
 and so forth.  For example, the commands<tscreen>
<verb>&lcub;rmon&rcub; pb 60 1 2
</verb></tscreen>
<verb>&lcub;rmon&rcub; pw 70 04F2 002F
</verb>
<verb>&lcub;rmon&rcub; pl 80 8000FF04 8000FF0F 80FFFFFF
</verb>

will put the value 01 into location 00000060 and 02 into the location 00000061,
 put the value 04F2 into location 00000070 and 002F into location 00000072,
 and put the value 8000FF04 into location 00000080, 8000FF0F into location 00000084
 and 80FFFFFF into  location 00000088 respectively

<item>fb|fw|fl start_address end_address value: These  commands fill the memory
 given by the start and end address with the given value.  Memory can be addressed
 in byte, short word or long word sizes using the fb, fw and fl  commands  respectively.
   The start and ending addresses must be aligned to the given memory sizes.
  For example, the commands<tscreen>
<verb>&lcub;rmon&rcub; fb 60 70 8F
</verb></tscreen>
<verb>&lcub;rmon&rcub; fw 60 70 FF8F
</verb>
<verb>&lcub;rmon&rcub; fl 80 90 00FFFF11
</verb>

will put the value 8F into all bytes (inclusive) between locations 00000060
 and 00000070, put the value FF8F into all short words (inclusive) between locations
 00000060 00000070, and put the value 00FFFF11 into all long words (inclusive)
 between locations 00000080 and 00000090.

<item>sb|sw|sl start_address end_address value: These  commands  search the memory
 given by the start and end addresses for the first occurrence of the given
 value and will print out the address where the value was found and the value.
  If the given value is  not  found, then nothing will be printed.  Memory can
 be addressed in byte, short word or long word sizes using the sb, sw and sl
 commands respectively.
<item>cb|cw|cl start_address end_address value: These commands compare successive
 memory locations given by the start and end addresses with the  given value
  and  will  print out the address and it's contents of the end_address, if
 all the memory was the same, or the address of the first location where the
 value was different to the given value along  with the  different  value. 
 Memory can be addressed in byte, short word or long word sizes using the cb,
 cw and cl commands respectively.
<item>tb|tw|tl start_address end_address seed: These commands generate pseudo-random
 values and store these  values  in  successive  memory  locations given  by
 the start and end addresses. When all the memory has been filled, the memory
 is read and it's contents is compared with what was written.  Memory can be
 addressed in byte, short word or  long  word sizes using the tb, tw and tl
 commands respectively. The  given  seed  will initialize the pseudo-random
 number generator.  If successive executions of this command use the same seed,
 then the random values will always be the same. When the random values are
 being written, a dot ('.') will be printed for each location. When the  read
 is  being  performed, a dot ('.') will be printed if the data equals what was
 written, else an 'X' will be printed.  For example<tscreen>
<verb>&lcub;rmon&rcub; tw 60 70 7B
</verb></tscreen>
<verb>Writing:
</verb>
<verb>Checking:
</verb>
<verb>&lcub;rmon&rcub;
</verb>

<item>m start_address end_address mask: This command will run low level memory
 tests on the given memory range.  The start  and  end  addresses must be long
 word aligned. If the test passes the message Passed. will be printed, and if
 it fails the message Failed. will be printed. The given mask will determine
 what type of tests are run. The table below shows what each mask will do. The
 tests essentially write to memory and then read from memory comparing what
 was read with  what  was written.   The  first twelve tests below first write
 to all the memory specified and then reads all the memory specified, the next
 twelve tests do an immediate read after the write.  The masks  can  be  or'd
 together to run multiple tests.<tscreen>
<verb>0x0001         Fill each byte with 0x00
</verb></tscreen>
<verb>0x0002         Fill each byte with 0xFF
</verb>
<verb>0x0004         Fill alternate bytes with 0x55 then 0xAA
</verb>
<verb>0x0008         Fill each byte with the two's complement of it's address
</verb>
<verb>0x0010         Fill each word with 0x0000
</verb>
<verb>0x0020         Fill each word with 0xFFFF
</verb>
<verb>0x0040         Fill alternate words with 0x5555 then 0xAAAA
</verb>
<verb>0x0080         Fill each word with the two's complement of it's address
</verb>
<verb>0x0100         Fill each long word with 0x00000000
</verb>
<verb>0x0200         Fill each long word with 0xFFFFFFFF
</verb>
<verb>0x0400         Fill alternate long words with 0x55555555 then 0xAAAAAAAA
</verb>
<verb>0x0800         Fill each long word with the two's complement of it's address
</verb>
<verb>0x0001000      Fill each byte with 0x00
</verb>
<verb>0x0002000      Fill each byte with 0xFF
</verb>
<verb>0x0004000      Fill alternate bytes with 0x55 then 0xAA
</verb>
<verb>0x0008000      Fill each byte with the two's complement of it's address
</verb>
<verb>0x0010000      Fill each word with 0x0000
</verb>
<verb>0x0020000      Fill each word with 0xFFFF
</verb>
<verb>0x0040000      Fill alternate words with 0x5555 then 0xAAAA
</verb>
<verb>0x0080000      Fill each word with the two's complement of it's address
</verb>
<verb>0x0100000      Fill each long word with 0x00000000
</verb>
<verb>0x0200000      Fill each long word with 0xFFFFFFFF
</verb>
<verb>0x0400000      Fill alternate long words with 0x55555555 then 0xAAAAAAAA
</verb>
<verb>0x0800000      Fill each long word with the two's complement of it's address
</verb>
<verb>0x1000000      Fill alternate long words with 0x00000000 then 0xFFFFFFFF
</verb>

<item>r start_address end_address read_size:: This  command  will  generate 
 and print a 32-bit Cyclic-Redundancy-Check value for the block of memory extending
 from start_address to end_address using reads of the size specified by  read_size
  which  can either  be  1, 2 or 4 for byte, word or long word reads respectively.
  The start and end addresses must be long word aligned.
</itemize>
<item>FLASH MEMORY COMMANDS: The Flash RAM used is AMD's Am29F040, a 4Mb (512k
 x 8bit) device that is comprised  of  8  equi-sized  sectors with  each  sector
  of  64Kb.   The  board  may  potentially have a second Flash RAM chip.  The
 total storage, regardless of the number of Flash RAM chips is divided into
 4 regions,  the first 3 are each 1  (64kB)  sector and  contain  the Bootstrap,
  Raid Configuration and Husky Scripts at the CPU addresses of BFC00000,  BFC10000
 and BFC20000 respectively.  The Main region contains 5 64Kb sectors (starting
 at BFC30000) and optionally  all 8  64Kb sectors of the second FLASHram (starting
 at BFC80000).  If this second chip is present there is then a total of 13 64Kb
 sectors for the main raid code.  The Manufacture ID and Device ID for the AMD
 Am29F040 is  01 and  A4  respectively.   Thus  the  text  &dquot;Flash: 01A4&dquot;
 is printed on either of the E command or the W command accessing this device.
  Attempting to erase or write to the Boot sector will always cause  an  &dquot;Illegal
  Flash RAM address range&dquot;.
<itemize>
<item>E sector_address: An  entire  region  can be bulk erased by the 'E' command
 by specifying an address in that region,  the main region will erase all sectors
 starting with that sector containing the nominated address and erase to  the
 end of that region, but not crossing a chip boundary.  Thus the 'E BFC40000'
 command will erase the last 4 sectors of the first chip.  The  'E BFC30000;
 E BFC8000' commands will erase the last 5 sectors  of the first chip and then
 erase the entire second Flash RAM chip (if it is present).  Attempting to erase
 a non-existent second chip cannot report an error,  however a negative number
  is  printed  to indicate other errors,  as described in the following table.
<verb>Error                 Fault Description
</verb>
<verb>-1                    Illegal Flash RAM address range.
</verb>
<verb>-2                    A sector within given range that is Write Protected.
</verb>
<item>W sector_address source_address byte_count: This  command  will  copy 
 byte_count bytes of data from source_address to EEPROM locations starting at
 sector_address.  The number of bytes copied or on error, a negative number
 will be printed. The negative error numbers  are  described in the table below.
  Optionally a W command may appear without any arguments, in this case the
 sector_address will be that specified by a  previous  E  command  and  the
 source_address  and  byte_count will be that given to and that printed by,
  respectively,  a previous T command (see below).  This command,  unlike the
 E command,  will modify  the  contents  of  the  second Flash RAM chip,  if
 it is implied by sector_address plus byte_count being equal or greater than
 the CPU address BFC80000.  An attempt to write with a byte_count of 0 is not
 an error,  and will cause only the Manufacturer and Device ID to be printed.<tscreen>
<verb>Error                 Fault Description
</verb></tscreen>
<verb>-1                    Illegal Flash RAM address range
</verb>
<verb>-2                    A sector within the address range that is Write Protected
</verb>
<verb>-3                    On a failed Byte Program command
</verb>
</itemize>
<item>NETWORK COMMANDS: The  second  RS232  port  on the RaidRunner can be used
 to download programs and data into memory from a host. This port can run the
 TCP/IP SLIP protocol and the Trivial File Transfer Protocol (TFTP) is available
 for file transfer. Three  variable  are available to effect download file transfers
 from a remote host. These are the remote host IP address, the local IP address
 (of the RaidRunner) and the name of the file on the remote host that is to
 be downloaded.  These  variables  have  default values of C02BC60E (192.43.198.14),
 C02BC6FD (192.43.198.253) and /usr/raid/lib/raid.bin where are the remote host
 IP address, local IP address and remote host's file to  down- load  respectively.
  These  default  values  are dynamic in that, if you change them, they will
 revert back to their default values at power-on or whenever the boot monitor
 is started. The following commands manage these variables and file transfers.
<itemize>
<item>A &lsqb;remote_ip_address &lsqb;local_ip_address&rsqb;&rsqb;: With no arguments,
 this command prints, in hexadecimal, the dynamic remote and local IP addresses
  used by TFTP and SLIP. To  change the remote IP address, execute this command
 with only one argument - the IP address (in hexadecimal) of the remote host.
 To change the local IP address (of the RaidRunner), the execute this command
 with  two  arguments,  the first  being  the  IP address of the remote host
 and the second being the IP address of the RaidRunner. Remember both addresses
 must be in hexadecimal.
<item>F &lsqb;filename&rsqb;: With no arguments, this command prints the filename
 of the file to download from the remote host. To change the filename, specify
 it as the argument to this command. Remember, the permissions on this file
 on the remote machine, must be set to allow remote  TFTP  access by the RaidRunner.
<item>P: This  command  will  ping  (send an ICMP ECHO request packet and time
 the response) the remote internet host.  If the remote host responds, the message<tscreen>
<verb>Sending echo request...
</verb></tscreen>
<verb>Got response after 0x0000nn ms
</verb>


will be printed. nn is the number of milliseconds it took for the  remote
  host  to  respond. If the remote host does not respond within 10 seconds,
 the message
<verb>Sending echo request...
</verb>
<verb>timeout after 10 seconds
</verb>


will be printed.

<item>T start_address end_address: This  command will transfer from the remote
 host the stored filename into a block of memory starting at
<item>start_address and limited to end_address. The number of bytes that will
 be transferred will  be  either the  size of the remote file or the value computed
 by end_address - start_address + 1, whichever is the lessor.  Whilst the data
 is being transferred, a dot ('.') will be printed  for  each  packet  of  data
 transferred.  At  the end of a successful transfer, the number of bytes transferred
 will be printed. If the transfer fails, an appropriate error message will be
 printed.

The following two examples show the transfer of the raid binary and the
  transfer  of  the  RaidRunner's  /bin directory  from  a remote host. The
 remote host's IP address is 192.43.198.101 (C02BC665), the RaidRunner's IP
 address is  192.43.198.200  (C02BC6C8)  and  the  two  files  concerned  will
  be  /usr/raid/lib/raid.bin  and /usr/raid/lib/raid.rc  (raid  binary  and
 /bin directory respectively). The raid.bin file will be written into the bank
 of flash ram starting at address bfc10000 and the raid.rc file will be written
 into the two  consecutive banks of flash ram at address bfc08000 and bfc0c000.
<verb>&lcub;rmon&rcub; &lcub;first transfer the raid binary - /usr/raid/lib/raid.bin&rcub;
</verb>
<verb>&lcub;rmon&rcub; F /usr/raid/lib/raid.bin
</verb>
<verb>&lcub;rmon&rcub; A C02BC665 C02BC6C8
</verb>
<verb>&lcub;rmon&rcub; P
</verb>
<verb>Sending echo request...
</verb>
<verb>Got response after 0x000013 ms
</verb>
<verb>&lcub;rmon&rcub; T 80300000 803fffff
</verb>
<verb>&lcub;rmon&rcub; E bfc10000; &lcub;erase the Flash EEPROM address for raid.bin
 to be stored&rcub;
</verb>
<verb>**
</verb>
<verb>70000
</verb>
<verb>&lcub;rmon&rcub; W bfc10000 80300000 5BDA0; &lcub;copy downloaded raid.bin
 into flash&rcub;
</verb>
<verb>5BDA0
</verb>
<verb>&lcub;rmon&rcub;
</verb>
<verb>&lcub;rmon&rcub; &lcub;now transfer the raid /bin directory - /usr/raid/lib/raid.rc&rcub;
</verb>
<verb>&lcub;rmon&rcub; F /usr/raid/lib/raid.rc
</verb>
<verb>&lcub;rmon&rcub; A C02BC665 C02BC6C8
</verb>
<verb>&lcub;rmon&rcub; P
</verb>
<verb>Sending echo request...
</verb>
<verb>Got response after 0x000013 ms
</verb>
<verb>&lcub;rmon&rcub; T 80300000 803fffff
</verb>
<verb>&lcub;rmon&rcub; E bfc08000; &lcub;erase the two consecutive blocks of
 flash ram where raid.rc&rcub;
</verb>
<verb>4000
</verb>
<verb>&lcub;rmon&rcub; E bfc0c000; &lcub;is to be stored&rcub;
</verb>
<verb>4000
</verb>
<verb>&lcub;rmon&rcub; W bfc08000 80300000 4000; &lcub;copy the first 0x4000
 bytes&rcub;
</verb>
<verb>4000
</verb>
<verb>&lcub;rmon&rcub; W bfc0c000 80304000 4000; &lcub;copy the next 0x4000 bytes&rcub;
</verb>
<verb>4000
</verb>
<verb>&lcub;rmon&rcub;
</verb>

<item>Sno ABC-12345: Prints / sets the serial number.  Without an argument the
 current serial number will be printed,  if no serial number has been set then
 nothing is printed.  If there any trailing characters after 'Sno'  command,
 then  this will indicate that these characters are to be set permanently as
 a serial number. A serial number may only be set once, there after any attempt
 to set another one will be ignored and  the current  serial  number  printed.
   If the serial number has to be re-set then the flashram needs to be reblown
 as if it were brand new.  Note that when setting the serial number for
 the first time,  the exact  format  of the command is very important.  There
 will be exactly one space after the the command 'Sno',  after which the next
 12 printable characters are taken as the serial number.  If there are less
 than  12  characters  (before the carriage return),  then blank characters
 are padded on the right-hand side.

It is suggested that a serial number be no greater than 10 characters and
 consist of  upper  case  letters,   decimal  digits  and only a limited number
 of special characters such as '-' or '.' characters. The main raid code will
 truncate the serial number to 10 characters if a  revision  level  is  present.
 The main raid code will,  if the revision level is present,  append the revision
 level immediately after the serial number and present the combined string as
 the serial number in an inquiry command.

<item>Rev A: Prints / sets the board revision level.  Without an argument the
 current revision level will be printed as an upper case letter (from 'A' to
 'Z').  If immediately following the 'Rev' command there is a space and a single
 upper case letter then this will indicate that this revision level is to set
  permanently. The revision level can be increased (e.g. from 'A' to 'B' to
 'C' etc.),  but can not ever be decreased.
</itemize>
<item>DIAGNOSTICS: 

x000 General form of a diagnostic command it that is it preceded by an
 x and then immediately followed by  a hexi-decimal  no.   Most  diagnostics
  will loop permanently requiring a power off/on cycle to stop the diagnostic.
<itemize>
<item>x000 chip: Will continually assert / de-assert most SCSI bus signals. 
 These include DB0-15, I/O, REQ,  C/D,  SEL, MSG,  RST,  ACK, BSY, ATN.  The
 DP0 and DP1 (i.e.  parity bits) can not be assert / de-asserted in this fashion.
<item>x001 chip: Will continually assert / de-assert most SCSI bus signals in
 such a fashion as to indicate  the  number of  the  SCA  connector that this
 pin would be connected to.  This count is w.r.t. to the LED1 and LED2 when
 used to trigger a scope (on the falling edge).  Each complete group of ten
 counts are coalesced to facilitate counting on a scope.  The counts are:-<tscreen>
<verb>7  - DB11       14 - SEL         21 - DB7        28 - DB0
</verb></tscreen>
<verb>8  - DB10       15 - MSG         22 - DB6        29 - DP1 (*2)
</verb>
<verb>9  - DB9        16 - RST (*1)    23 - DB5        30 - DB15
</verb>
<verb>10 - DB8        17 - ACK         24 - DB4        31 - DB14
</verb>
<verb>11 - I/O        18 - BSY         25 - DB3        32 - DB13
</verb>
<verb>12 - REQ        19 - ATN         26 - DB2        33 - DB12
</verb>
<verb>13 - C/D        20 - DP0 (*2)    27 - DB1
</verb>


Note  that  the  RST  line (marked *1 above) is pulsed only once after
 the last pin is pulsed (i.e after DB12) and that the parity lines (marked as
 *2 above) can not be pulsed.

<item>x002 dst_addr src_addr length: Calls the C library routine memcpy with
 three arguments of destination  address,   source  address  and length (all
 in hex).
<item>x003 200000 ffffff and x004 200000 ffffff: Two  commands  are used to exercise
 Battery Backed-up DRAM.  The x003 command will set the memory range as suggested
 above.  The value of 200000 is one location past the last used flash monitor
 memory  location,  ffffff is the last memory location of 8Mb of DRAM (this
 latter figure can be varied according to available DRAM memory).  The DRAM
 starting at 0 will be modified to contain :-<tscreen>
<verb>00: 0x3C1A9FC0   &lsqb; lui k0,0x9fc0 &rsqb;
</verb></tscreen>
<verb>04: 0x3C1B3C1A   &lsqb; lui k1,0x3c1a &rsqb;
</verb>
<verb>08: 0xAC1B0000   &lsqb; sw  k1,(zero) &rsqb;
</verb>
<verb>0C: 0x3C01A000   &lsqb; lui at,0xa000 &rsqb; 
</verb>
</itemize>

Location 0 is the start of the restart pseudo interrupt handler.  The x004
 command is then  used  after restoring  power  to  check for this bit pattern.
  It is important that the arguments given to x003 are exactly the same as those
 given to x004.  Any words detected that are different are printed,  if  there
 are no differences then nothing (but the next prompt) is printed.

<item>NOTE: As a side effect of the above executing the above restart pseudo
 interrupt handler on restoring power,  location 0 will be patched with 0x3C1A0000
 to prevent memory tests  and  autobooting  the  main raid code.  This feature
 can be re-enabled by depositing 0 into location 0 (i.e `pl 0 0`).
</itemize>


<sect1>RRSTRACE - disassemble scsihpmtr monitor data
<p>
<itemize>
<item>SYNOPSIS: rrstrace -f monitor_file &lsqb;-b bcnt&rsqb; &lsqb;-v&rsqb;
<item>DESCRIPTION: rrstrace  will disassemble the monitoring data collected by
 scsihpmtr which has been transferred to a host via ssmon. rrstrace will additionally
 analyze all scsi reads and look for  sequences  of  reads  and  report  them.
  This repeating sequence is referred to as a 'natural read'.  This data can
 be then used for a more optimal configuration of the raid.  The natural reads
 are reported via a starting block size followed by the total length (in blocks)
 of the natural read, how many reads made up the natural read and finally how
 many times it occurred. At the end the number of natural reads found are printed
 along with how many were looked for and how  many  actually  existed.  By default
 up to 256 different natural reads can be scanned for, but if more are required
 then the -b bcnt option can be given to allocate a deeper search. Note that
 a natural read that occurs only once is recorded but not printed out.
<item>OPTIONS:
<itemize>
<item>-f monitor_file: Specify the name of the file from which the data is to
 be read
<item>-b bcnt: Specify a larger natural read analysis count
<item>-v: Turn on verbose mode and hence print out every scsi instruction. In
 verbose mode, each line of output from rrstrace is of the form time chipno
 lun ssid msg_id tag command, where:
<itemize>
<item>time: is the time the command occurred
<item>chipno: is the chip number (hostport) upon which the command came in
<item>lun: is the target lun the command was directed to
<item>ssid: is the scsi id of the initiator (i.e host)
<item>msg_id: is the scsi message id of the command
<item>tag : is the scsi tag number of the command or -1 if no tag is associated
<item>command: is the scsi command itself in text or if unknown to rrstrace the
 12 byte scsi command block will be printed. In the case of read and write commands,
 the block address and length is printed along with the block address of the
 next sequential read/write command if the next command were to be sequential
 (this address is parenthesized). If the command has the 'Force Unit Access'
 bit set, then FUA is appended to the line. The scsi Read_6, Write_6, Read_10
 and Write_10 commands will be printed as R6, W6, R10 and W10 respectively.
</itemize>
</itemize>
<item>SEE ALSO: ssmon, scsihpmtr
</itemize>


<sect1>RSIZE - estimate the memory usage for a given raid set
<p>
<itemize>
<item>SYNOPSIS: rsize type cachesize iosize nbackends
<item>DESCRIPTION: rsize  prints  an  estimate of the amount of memory (in bytes)
 a running raid set will use, given the raid set type, the amount of cache allocated
 to it, the raid set iosize and the number of backends in the raid set.
<item>SEE ALSO: rconf
</itemize>


<sect1>SCN2681 - access a scn2681 (serial IO device) as console
<p>
<itemize>
<item>SYNOPSIS: bind -k &lcub;scn2681 &lsqb; value &rsqb;&rcub; bind_point
<item>DESCRIPTION: scn2681 allows the target hardware using the SCN2681 serial
 IO chip to be accessed via the bind_point in the K9 namespace. If no optional
 argument is given channel A in the chip is used. If value is 0 then  channel
  A  (serial port)  is  used.  If value is 1 then channel B (serial port) is
 used.  If value is 2 then the input port (parallel) is used.  If value is 3
 then the output port (parallel) is used. The special file scn2681 is only available
 when the target is special hardware (containing a SCN2681).
<item>SEE ALSO: cons
</itemize>


<sect1>SCSICHIPS - print various details about a controller's scsi chips
<p>
<itemize>
<item>SYNOPSIS: scsichips
<item>DESCRIPTION: scsichips prints details about the RaidRunner scsi chips.
<item>OPTIONS: Three sets of numbers are printed. The first two numbers are the
 number of hostports (chips) and the number of backend channels (chips). The
 rest of the numbers printed are the hostport then backend channel chip  indexes.
 The chip addresses can be used in binding them to a entrypoint in the kernel.
<item>EXAMPLES:

For a RaidRunner controller with one hostport and six backend channels
 scsichips will print
<verb>1 6 6 0 1 2 3 4 5
</verb>

which  says that there is 1 hostport chip, 6 backend channels, the address
 of the hostport chip is 6 and the addresses of the backend channel chips are
 0, 1, 2, 3, 4 and 5.

For a RaidRunner controller with two hostports and six backend channels
 scsichips will print
<verb>2 6 6 7 0 1 2 3 4 5 
</verb>

which says that there are 2 hostport chips, 6 backend channels, the addresses
 of the hostport chips are 6  and 7 and the addresses of the backend channel
 chips are 0, 1, 2, 3, 4 and 5.
<item>SEE ALSO: hwconf, scsihpfs, scsihdfs
</itemize>


<sect1>SCSIHD - SCSI hard disk device (a SCSI initiator)
<p>
<itemize>
<item>SYNOPSIS<tscreen>
<verb>bind -k &lcub;scsihd chipNumber scsiTargetId
</verb></tscreen>
<verb>&lsqb;scsiTargetLUN&rsqb;&rcub; bind_point
</verb>
<verb>cat bind_point
</verb>
<verb>ctl
</verb>
<verb>raw
</verb>
<verb>partition
</verb>
<verb>data
</verb>
<verb>rconfig
</verb>

<item>DESCRIPTION: scsihd  is  a  SCSI  hard  disk device. In SCSI jargon it
 is called the &dquot;initiator&dquot; while the disk it is talking to is referred
 to as the &dquot;target&dquot;. The disk is known in SCSI as a &dquot;direct
 access  device&dquot;.  Currently  this  device  adopts the SCSI id 7 and attempts
 to access a disk with a SCSI id of scsiTargetId. The &dquot;logical unit number&dquot;
 (LUN) within the scsiTargetId that is accessed is scsiTargetLUN (or LUN  0
  if not  given). Multiple SCSI buses are supported (with typically one device
 per bus) and are distinguished by the chipNumber.

The SCSI disk device is bound into the namespace at bind_point. A one level
 directory  is  made  at  the bind_point  containing  the files: &dquot;raw&dquot;,
 &dquot;data&dquot;, &dquot;partition&dquot;, &dquot;rconfig&dquot; and &dquot;ctl&dquot;.
 The &dquot;partition&dquot; file is a small portion at the end of the disk
 used for storing partition information (in plain ASCII). The &dquot;ctl&dquot;
 and &dquot;rconfig&dquot; files are for internal RaidRunner use.  (The &dquot;rconfig&dquot;
 file will be a backup copy of the RaidRunner configuration area).  The &dquot;data&dquot;
 file is the usable part (i.e. the vast majority) of  the space  available 
 on  the SCSI disk connected to the SCSI bus on which this device is an initiator.
  The file &dquot;raw&dquot; addresses the whole disk less the partition block.

The current raid hardware has six fast wide SCSI-2 buses numbered 0 to
 5 and two fast  wide  buses  num- bered 6 and 7.  Usually the first six fast
 wide SCSI-2 buses are set up as initiators (i.e. bind scsihd) while the two
 fast wide SCSI buses are set up as targets (i.e. bind scsihp).

Current implementations make the device name hd synonymous with scsihd.
 Therefore:
<verb>bind -k &lcub;hd chipNumber scsiTargetId 
</verb>

&lsqb;scsiTargetLUN&rsqb;&rcub; bind_point has the same effect as the similar
 line in the synopsis.
<item>SEE ALSO: scsihp
</itemize>


<sect1>SCSIHP - SCSI target device
<p>
<itemize>
<item>SYNOPSIS<tscreen>
<verb>bind -k &lcub;scsihp chipNumber scsiid&rcub; bind_point
</verb></tscreen>
<verb> 
</verb>
<verb>cat bind_point
</verb>
<verb>scsiid         &num; this device's scsi id
</verb>
<verb>cat bind_point/scsiid
</verb>
<verb>0
</verb>
<verb>...      &num; this device's LUN within SCSI id scsiid
</verb>
<verb>7
</verb>
<verb>cat bind_point/scsiid/0
</verb>
<verb>data      &num; scsi data channel for SCSI id scsiid LUN 0
</verb>
<verb>cmnd      &num; scsi command channel for SCSI id scsiid LUN 0
</verb>

<item>DESCRIPTION: scsihp  is  a  SCSI  target device. A &dquot;target&dquot;
 in SCSI jargon performs commands issued by an &dquot;initiator&dquot; which
 is usually a general purpose computer. Normally a SCSI target is an integral
  part  of  a  &dquot;direct access  device&dquot;  (i.e.  a  disk)  but  in
 a raid, the controller needs to look like a target to external users.  Multiple
 SCSI buses are supported (with typically one device per bus) and are  distinguished
  by the chipNumber.

The SCSI target device is bound into the namespace at bind_point. A three
 level directory is made at the bind_point. The first level is the SCSI id (as
 specified by scsiid) for this device. The second level is the  LUN  within
  that scsi id. The third level contains the files: &dquot;data&dquot; and &dquot;cmnd&dquot;
 which are used for SCSI data phases and command/status phases respectively.

A scsi target command interpreter called stargd is designed to &dquot;mate&dquot;
 with this device.

The current raid hardware has six fast narrow SCSI buses numbered 0 to
 5 and two fast  wide  buses  num- bered 6 and 7.  Usually the six fast narrow
 SCSI buses are set up as initiators (i.e. bind scsihd) while the two fast wide
 SCSI buses are set up as targets (i.e. bind scsihp).

<item>SEE ALSO: scsihd, stargd
</itemize>


<sect1>SET - set (or clear) an environment variable
<p>
<itemize>
<item>SYNOPSIS
<itemize>
<item>set name
<item>set name value ...
</itemize>
<item>DESCRIPTION: set allows the value (or list of values) associated with an
 environment variable to be changed. When no value is given then the environment
 variable name has its value set to NIL. When one value is given then the environment
 variable name is set to that value. When multiple values are given then the
 environment variable  name is set to that list of values.
<item>NOTE: set  is  a &dquot;built-in&dquot; in the Husky shell. This means
 a new shell is _not_ thrown to execute this command unless some other action
 forces it.   Setting  an  environment variable in a sub-shell has no effect
 once the sub shell exits to its parent shell. This is why throwing a sub-shell
 to execute set would be pointless. Operations such as command substitution
 (i.e. `set ...') and command line file redirection force a command to be executed
 in a sub-shell and  hence defeat the purpose of set. Hence the set command
 (or at least &dquot;built-in&dquot;) should appear in a simple expression to
 avoid surprises.
</itemize>


<sect1>SCSIHPMTR - turn on host port debugging
<p>
<itemize>
<item>SYNOPSIS:
<itemize>
<item>scsihpmtr -c portnumber storage_size
<item>scsihpmtr -b
<item>scsihpmtr -d
<item>scsihpmtr -e
<item>scsihpmtr -p count
<item>scsihpmtr -r
<item>scsihpmtr -w
</itemize>
<item>DESCRIPTION: scsihpmtr,  if enabled in the RaidRunner kernel, will create
 a volatile internal store and save details of all scsi commands which come
 in on a specified host port or set of host ports. This data can then be  uploaded
  to the host via the scsi monitor (ssmon) and analyzed as appropriate.
<item>OPTIONS:
<itemize>
<item>-c portnumber storage_size: Specify  and  allocate a volatile storage area
 of storage_size bytes and monitor and save all scsi commands that appear on
 the given portnumber.  The portnumber is the chip number of the host port 
 on  the raid controller.  If you specify a port number of 8, then all host
 ports will be monitored.
<item>-b: Perform natural read analysis for use in possible reconfiguration of
 RaidRunner.
<item>-d: Delete any volatile storage containing monitored data and hence stop
 monitoring.
<item>-e: Temporarily  disable  the monitoring (and hence storage) of scsi commands.
  Monitoring must be disabled BEFORE uploading the monitored data to the host
 via ssmon.
<item>-p count: Print out both details of what is being monitored and the first
 count stored scsi commands. The details printed are the total number of commands
 that  can  be  recorded,  the  current  number  of recorded  commands, the
 current  monitoring state (0 disabled, 1 enabled) and the monitored host port
 number. Each line of scsi commands printed will time the command occurred a
 hex word containing lower 3 bits the chip number (hostport) the command was
 on next 3 bits the scsi id of the command initiator (i.e host) next byte is
 the scsi message id of the command   next two bytes is the scsi tag number
 of the command a 12 byte scsi command header block
<item>-r: Reset the monitoring of scsi commands. This will cause all previously
 monitored data to be lost.
<item>-s: Re-enable the monitoring (and hence storage) of scsi commands.
<item>-w: Enable wrap around mode. By default, scsihpmtr will stop recording
 scsi commands once it has  used  all the  storage  area  allocated.  If  wrap
  around mode is enable, then scsi commands will continue to be recorded, wrapping
 round the storage area.
</itemize>
<item>SEE ALSO: smon, ssmon, SCSI Standards for formats of scsi commands.
</itemize>


<sect1>SETENV - set a GLOBAL environment variable
<p>
<itemize>
<item>SYNOPSIS: setenv name value ...
<item>DESCRIPTION: setenv allows the value (or list of values) associated with
 a GLOBAL environment variable to be changed (or created). When one value is
 given then the GLOBAL environment variable name is set to that value. When
 multiple values are given then the GLOBAL environment variable name is set
 to that list of values.
<item>NOTE: A GLOBAL environment variable is one which is stored in a non volatile
 area on the RaidRunner and hence is available between successive power cycles
 or reboots. These variables ARE NOT the same as husky environment variables.
 The non volatile area is co-located with the RaidRunner Configuration area.
<item>SEE ALSO: printenv, unsetenv, rconf
</itemize>


<sect1>SDLIST - Set or display an internal list of attached disk drives
<p>
<itemize>
<item>SYNOPSIS
<itemize>
<item>sdlist
<item>sdlist -p
<item>sdlist backend_triplett_list
</itemize>
<item>DESCRIPTION: sdlist  maintains a list of disk backends, in rank, chip,
 scsi lun form for a RaidRunner. This list is used by various commands to save
 those commands from continuously probing for all possible backends. When run
 without arguments, sdlist zero's the internal list and probes for all disk
  backends  rebuilding  the list. Typically,  sdlist will be run with a list
 provided to it by way of it's arguments. For example, on a RaidRunner with
 one rank (at scsi id 1) and six disks with all luns at zero the following would
 be run.<tscreen>
<verb>sdlist `hwconf -D'
</verb></tscreen>

which would equate to
<verb>sdlist 0.1.0 1.1.0 2.1.0 3.1.0 4.1.0 5.1.0
</verb>

and those six tripletts would be stored in the list, with sdlist having
 already  deleted  any  already  stored list. To see what this internal list
 contains, the -p option can be given and the list will be printed. This  command
 is typically executed during autoboot and would not be executed interactively
 unless the user is performing unusual backend manipulations and is debugging
 the process.
<item>SEE ALSO: rconf
</itemize>


<sect1>SETIV - set an internal RaidRunner variable
<p>
<itemize>
<item>SYNOPSIS:
<itemize>
<item>setiv
<item>setiv name value
</itemize>
<item>DESCRIPTION: setiv allows the value of an internal RaidRunner variable
 to be changed or lists all changeable internal variables (no argument). When
 a value is given then the internal RaidRunner variable name is set to that
 value. If no value is given the all settable internal variables are listed.
<item>NOTES: As different models of RaidRunners have different settable internal
 variables see your  RaidRunner's  Hardware Reference manual for a list of variables
 together with the effect of changing them. These variables are run-time variables
 and hence must be set each time the RaidRunner is booted.
<item>SEE ALSO: getiv
</itemize>


<sect1>SHOWBAT - display information about battery backed-up ram
<p>
<itemize>
<item>SYNOPSIS: showbat &lsqb;-a&rsqb; &lsqb;-n&rsqb; &lsqb;-s&rsqb; &lsqb;-t&rsqb;
<item>DESCRIPTION: showbat will print (to standard output) information about
 the installed battery backed-up ram.
<item>OPTIONS :
<itemize>
<item>-a: Print  address  information  about  battery  backed-up ram. The addresses
 printed are the base address, start of tag address, start of reserved area
 address, start of cache data address and the first  unused byte address.
<item>This is the default if no options are given.
<item>-n: Print the number of tags in battery backed-up ram.
<item>-s: Print the status of the battery backed-up ram.
<item>-t: For  each  tag  in  battery  backed-up  ram,  print it's value and
 the location of it's data along with details of the cache range it belongs
 to. If the cache filesystem has not been created and the ranges added then
 this option will only print out the tag addresses and inform you that no ranges
 are available. If the data associated with the tag has partially written data
 in it, the tag will be flagged in the list.
</itemize>
<item>SEE ALSO: cachedump, cacherestore, cacheflush
</itemize>


<sect1>SHUTDOWN - script to place the RaidRunner into a shutdown or quiescent
 state
<p>
<itemize>
<item>SYNOPSIS: shutdown
<item>DESCRIPTION: shutdown  is  a husky script which is used to place the RaidRunner
 into the &dquot;shutdown&dquot; or quiescent state. The &dquot;shutdown state&dquot;
 is one in which the raid sets configured cannot be accessed by a host and all
 devices (disks) attached to the RaidRunner are in a low power usage state (i.e
 spun down). shutdown  first  set's all stargd's to a spin state of 2 which
 means that all host scsi medium-access commands will result in a CHECK CONDITION
 status and set the mode sense key to NOT READY and the additional mode  sense
 code  and  code  qualifier  to &dquot;LOGICAL UNIT NOT READY, MANUAL INTERVENTION
 REQUIRED&dquot;.  It will then flush the cache and finally spin down all backend
 devices attached. Note that the scsi monitors - smon, are not effected.
<item>SEE ALSO: stargd, mstargd, cache, spind
</itemize>
<sect1>SLEEP - sleep for the given number of seconds
<p>
<itemize>
<item>SYNOPSIS: sleep seconds
<item>DESCRIPTION: sleep causes the current K9 process to &dquot;sleep&dquot;
 for the given number of seconds. The argument seconds may be any integer or
 a fixed point number (e.g. 1.5). The resolution of timing is one clock tick
 (which varies according to the target hardware). If the sleep is interrupted
 before it completes then a &dquot;sleep interrupted&dquot; status message is
 returned otherwise NIL (i.e. true) is returned.
<item>SEE ALSO: K9sleep
</itemize>


<sect1>SMON - RaidRunner SCSI monitor daemon
<p>
<itemize>
<item>SYNOPSIS: smon &lsqb;-b blkprotocol&rsqb; &lsqb;-d debug_level&rsqb; -m
 moniker -h hport &lsqb;-n&rsqb; &lsqb;-r&rsqb; &lsqb;-1 stdout_fifo_file&rsqb;
 &lsqb;-2  stderr_fifo_file&rsqb; &lsqb;-3 status_file&rsqb; -s capacity device
 id lun
<item>DESCRIPTION: smon is a daemon process that simulates a SCSI-2 disk with
 modified Read and Write SCSI commands that implement a simple protocol which
 provides file transfer to and from the RaidRunner and remote command execution
 on the RaidRunner. The protocol is based on the SCSI  Read  and  SCSI  Write
 starting block addresses. smon  usually works closely with a special device
 (file system) that does the hardware interfacing and message interpretation
 for a  SCSI-2  target (see scsihp).

smon  has 3 mandatory switches, 8 optional
 switches and 3 mandatory positional arguments. The mandatory switches are the
 -s switch which specifies the size of  the SCSI-2 monitor store, the -m switch
 which specifies the moniker (name) of the target and the -h switch which specifies
 the controller host port the monitor will communicate over.

The  3 mandatory
 positional arguments are device, id and lun. These arguments are concatenated
 together to make the filename  of  the  low  level SCSI  target  device  driver.
  The second argument is the SCSI identifier number this target will respond
 to while the third argument is the  logical unit number (LUN) within that SCSI
 identifier which the target represents. An error will occur during daemon initialization
 unless the  following files (with appropriate characteristics) are found: 
<itemize>
<item>device/id/lun/cmnd
<item>device/id/lun/data
</itemize>
<item>OPTIONS

The optional  switches  may  appear  in any order but if present must be
 before the positional arguments.

<itemize>
<item>-b blkprotocol: Change the block numbers used in the protocol (see below).
 By default the block numbers used in the protocol are 7, 8, 9 10, 11, 12, 13,
 14 and 15 for protocol elements  BLK_STDOUT,  BLK_STDERR, BLK_STATUS, BLK_ENDPROC,
 BLK_UPLOAD, BLK_STDIN, BLK_MONITOR BLK_RESET and BLK_RCONFIG respectively.
 To change  this  default list  of block numbers, specify a comma separated
 list of nine(9) unique block numbers.
<item>-d debuglevel: This switch is a debug flag. When given the command line
 arguments and other information  derived during initialization are echoed back
 to standard out and the debug level is set to  1. The debug levels are:
<itemize>
<item>0 no debug messages (default when &dquot;-d&dquot; not given)
<item>1 debug messages on all non-read/write commands
<item>2 debug messages on all commands 
</itemize>
<item>Debug messages are typically a single line per command and are sent to
 standard out. Serious  errors  are  reported to standard error irrespective
 of the current debug level. If the error is related to incoming data (from
 the SCSI initiator) then the daemon will continue. If the error cannot be recovered
 from, then the daemon terminates with an error message as its exit status.
 The debug level can be changed during the execution of a smon daemon by using
 the &dquot;-d&dquot; option on mstargd.
<item>-m moniker: This switch associates the moniker (i.e name) with the scsi
 monitor that  smon  is about to execute on. It provides a method of naming
 scsi monitors. The moniker can be a  maximum  of  32  characters. This switch
 is mandatory.
<item>-h hport: This switch advises smon which controller host port number it
 will be communicating over. This switch is mandatory.
<item>-n: This switch stops statistics being gathered. The default action is
 to collect statistics.
<item>-r: This switch is for restarting the daemon with as little disturbance
 to the initiator as possible. Usually the SCSI Unit  attention  condition 
 is set on reset (and when this daemon commences). When this switch is given
 the daemon starts in the idle state. Use with  care.  The default action (i.e.
  when the &dquot;-r&dquot; is not given) is to set a SCSI Unit attention condition
 so that the  first  SCSI command  received  will  have its status returned
 as &dquot;Check condition&dquot; (as required by the SCSI-2 standard).
<item>-1 stdout_fifo_file: Specify the name of the fifo data file where the standard
 output of any executed commands is to be sent (and read from).
<item>-2 stderr_fifo_file: Specify  the  name  of  the  fifo data file where
 the standard error output of any executed commands is  to  be  sent  (and 
 read from).
<item>-3 status_file: Specify  the  name of the fifo data file where the exit
 status of any executed command is to be written to (and read from).
<item>-s capacity: This mandatory switch informs the daemon what the size  in
  blocks this  SCSI  target  will represent. The value for capacity effects
 the response this target makes to the SCSI Read Capacity and  Mode Sense  (page
 4)  commands.  To simplify writing out large numbers certain suffixes can be
 used, see suffix.
<item>PROTOCOL: smon appears as a disk with the given capacity, scsi id and scsi
 lun to a host computer. By reading and writing to specific block locations
 on this disk, the host computer can send and have executed husky commands 
 on the  RaidRunner  and  read  back the command's standard output, error and
 status.  Additionally files can be both downloaded from the host onto the RaidRunner
 and uploaded from the RaidRunner onto the local host computer.

All reads and writes by the host need to be  in  multiples  of  512  byte
 blocks with null padding as appropriate. When WRITEing (from the host) to smon,
 the data, depending on the block number, contained in the write will be treated
 as follows -
<item>BLK_ENDPROC: Will kill any processes, started by smon, currently running
 on the RaidRunner.   The  contents  of  the write's data will be read but ignored.
<item>BLK_RESET: Will terminate any file transfers, kill any process(s) (started
 by smon)  currently running on the RaidRunner, close any files opened by smon
 and reset smon to it's initial state.  The contents of the write's data will
 be read but ignored.
<item>BLK_STDIN: If smon is in DOWNLOAD file transfer mode, the contents of the
 write's data will be written out to the download file on the RaidRunner. If
 not in DOWNLOAD file transfer mode, will asynchronously execute the contents
 of the write as a husky command. Before execution of the command, the command
 is checked to see if it is an internal file transfer smon command, and if so,
 will  initialize for file transfer.
<item>Any other: Will perform the write to the internal store. Up to 16 blocks
 of data will be stored in the raid configuration area.
<item>When READing (by the host) from smon, the data, depending  on  the  block
 number, contained in the read will be treated as follows -
<item>BLK_STDOUT: This read will return the currently available standard output
 from the previously executed command.  If the number of bytes of  stan<61> dard
 output is less than the size of the read's data the data will be padded with
 NULL's ('\0'). If the number of bytes  of  standard output  is  more  than
 the size of the read, then subsequent reads from BLK_STDOUT will transfer the
 rest  of  the  standard  output. Normally one would loop reads from BLK_STDOUT
 until the last character in the read buffer is NULL. If the previous command
 was a write to start a  download,  then  a read  of  one block will next be
 expected and will return either a block of NULL's or an error message indicating
 a problem with  the initialization of the download.
<item>BLK_STDERR: This read will return the currently available standard error
 out<75> put from the previously executed command in the same manner as BLK_STDOUT.
<item>BLK_ENDPROC: If the previously executed command (write to block BLK_STDIN)
 has not completed this read will return with it's buffer starting with &dquot;Process
 not finished&dquot; and NULL padded. If the command has completed then it will
 return a NULL filled buffer.
<item>BLK_STATUS: A read from this block will return the command's husky exit
 status (the &dollar;status variable).
<item>BLK_UPLOAD: Will first return either the UPLOAD handshake command (response
 to a UPLOAD write command) which is of the form UPLOAD nbytes where nbytes
 is the number of bytes in the file that has just been requested  to be uploaded
 from the RaidRunner or an error message, then all reads from this  block  onwards
  will  contain  the  next buffer from the uploaded file.
<item>BLK_MONITOR: Will first return either the MONITOR handshake command (response
 to a MONITOR write command) which is of the form MONITORSIZ nbytes where nbytes
 is the number of bytes of monitor data that will need to be transferred up
 to the host OR an error message if there is no monitoring data. All subsequent
 reads will upload the monitoring data.
<item>BLK_RCONFIG: Successively reading in data from this block will return successive
 data from the in-core raid configuration area. When a BLK_RESET is written,
 the internal smon index into  the in-core raid configuration area is reset
 (set to 0). When a number of blocks from BLK_RCONFIG are this internal index
 is incremented by the amount of data read. If more data is read than is available
 in the in-core raid configuration area, then the index is reset to 0.
<item>Any other: Will perform the read from the internal store.
<item>Internal Store: Typically, a host computer stores labels, boot and disk
 partition information on all disks. On most host computers, they usually only
 store this  information in a few blocks either at the start of the disk and/or
 near the end of the disk. Rather than smon reserving this space as a continuous
 piece of memory, most of which would not be used, an internal store of 16 512-byte
 blocks is created and maintains a mapping of host block addresses to the store.
 This store is copied to the raid configuration area noting the controller number
 and host port number smon is running on. If the store fills as a host computer
 writes many blocks to the smon disk,  the  additional data is discarded. If
 a host computer attempts to read blocks that have not been stored, then null
 fill data is returned.
</itemize>

<item>SIGNALS:

Two K9 signals are interpreted specially by smon.
<itemize>
<item>If the signal K9_SIGINT is received then smon will check to  see  whether
 there  is a command in progress and if so terminate it with a &dquot;Check
 condition&dquot; status and set the associated sense  key  to  &dquot;Command
  aborted&dquot;. smon will then return to its command (waiting) mode. 
<item>If  the  signal  K9_SIGTERM  is received then smon will do the same as
 it does for K9_SIGINT except it will exit the process rather than  going  to
 command (waiting) mode.
</itemize>

The SCSI initiator should interpret a sense key of &dquot;Command aborted&dquot;
 as the target unilaterally aborting a command in progress. The SCSI-2 standard
 suggests the initiator should retry the aborted command.

<item>EXAMPLE<tscreen>
<verb>smon -s 2080 -h 1 -m SMON167 /dev/hostbus/1 6 7
</verb></tscreen>


This line will invoke this daemon and try and open the following files:
<verb>/dev/hostbus/1/6/7/cmnd
</verb>


and
<verb>/dev/hostbus/1/6/7/data
</verb>


The &dquot;-s 2080&dquot; switch instructs this daemon to tell SCSI initiators
 that it is a 1040K disk. 

<item>SEE ALSO: scsihp, suffix, mstargd, stargd, mconf
</itemize>


<sect1>SOS - pulse the buzzer to emit sos's
<p>
<itemize>
<item>SYNOPSIS: sos &lsqb;count&rsqb;
<item>DESCRIPTION: sos will sound the buzzer in a plaintif &dquot;SOS&dquot;
 in Morse. If a count is given, it will repeat count times. The default count
 is 3.
<item>SEE ALSO: buzzer, warble
</itemize>
<sect1>SPEEDTST - Generate a set number of sequential writes then reads
<p>
<itemize>
<item>SYNOPSIS: speedtst -d device -n io_cnt -X bufsize &lsqb;-o offset&rsqb;
 &lsqb;-STRW&rsqb;
<item>DESCRIPTION: By default speedtst will perform io_cnt sequential writes
 of size bufsize bytes onto the device from the start of  the  device.  It 
 will  then  do io_cnt  sequential  reads  of  size  bufsize  bytes from the
 start of the device device. By default reads and writes are not checked for
 success. The output of this command provides the I/O transfer rates  in  Megabytes
 (MB) and million bytes (mb) for both the write and read sequences. The bufsize
 and offset values may have a suffix.
<item>OPTIONS: 
<itemize>
<item>-o offset: All  reads  and  writes  are to be performed offset bytes into
 the device. All reported values will be relative to this  offset.  The default
 is 0 i.e the start of the device.
<item>-r drives: The  bufsize  (set by -X bufsize) is expected to be to iosize
 of a Raid 5 raid set where drives is the  number  of  data  and  parity drive.
  A single bufsize operation is performed to a drive in each strip of the raidset
 in such a fashion that either the data  drive and  the  parity drive (the only
 two drives written too in a write operation) will not be the same drives as
 would have been  written too,  if  the previous operation on the previous stripe
 had been a write.  The default value is 0,  causing normal sequential  operations.
   This  option  is  used to simulate random operations on a raidset without
 the penalty of significant seek overheads.
<item>-R: By default speedtst will perform a write test then  a  read  test.
 Specifying this option, the write test will NOT be performed.
<item>-S: Normally  the  device, device, is opened in a default manner which
 may allow the host operating system to provide buffers when  writing  data
  to  it.  This  may  result in incorrect I/O through put rates. By setting
 this option, the device is opened in such a  way to  ensure that writes do
 not use any buffering and the individual write system calls do not return until
 the data is on the  device.
<item>-T: Normally  the  read  and write operations are NOT checked for success,
 that is the return values for  the  read  and  write  system calls are not
 checked for errors. To ensure each read and write is checked for any system
 error, use this flag.
<item>-W: By default speedtst will perform a write test then  a  read  test.
 Specifying this option, the read test will NOT be performed.
</itemize>
<item>SEE ALSO: randio, suffix
</itemize>
<sect1>SPIND - Spin up or down a disk device
<p>
<itemize>
<item>SYNOPSIS:
<itemize>
<item>spind up c.s.l
<item>spind down c.s.l
</itemize>
<item>DESCRIPTION: spind will either spin down or spin up a nominated disk drive
 via the SCSI-2 START command.
<item>OPTIONS:
<itemize>
<item>up: Spin up the disk drive. If the drive is already spun up nothing will
 occur.
<item>down: Spin down the disk drive. If the drive is already spun down nothing
 will occur.
<item>c.s.l: Identify the disk device by specifying it's channel, SCSI ID (rank)
 and SCSI LUN provided in the format &dquot;c.s.l&dquot;
</itemize>
<item>SEE ALSO: Product manual for disk drives used in your RaidRunner.
</itemize>
<sect1>SPINDLE - Modify Spindle Synchronization on a disk device
<p>
<itemize>
<item>SYNOPSIS
<itemize>
<item>spindle -c -p c.s.l &lsqb;-o rpl_offset&rsqb;
<item>spindle -m|M -p c.s.l &lsqb;-o rpl_offset&rsqb;
<item>spindle -s -p c.s.l &lsqb;-o rpl_offset&rsqb;
<item>spindle -g -p c.s.l
</itemize>
<item>DESCRIPTION: spindle will either modify or report on a disk device's spindle
 synchronization. This command will set or clear the Rotational Position Locking
 (RPL) bits in the disk device's GeometryParameter's mode sense page. If spindle
 correctly modifies the device's RPL bits, it will print out the resultant RPL
 bits  and the Rotational Offset byte of the device's Geometry Parameter mode
 sense page.
<item>OPTIONS:
<itemize>
<item>-p c.s.l: Identify  the disk device to modify by specifying it's channel,
 SCSI ID (rank) and SCSI LUN provided in the format &dquot;c.s.l&dquot;
<item>-c: Clear the RPL bits.
<item>-s: Set the RPL bits to 01b (0x1) which typically sets the device  to 
 operate  as  a  synchronized-spindle slave.
<item>-m: Set the RPL bits to 10b (0x2) which typically sets the device to operate
 as a synchronized-spindle master.
<item>-M: Set the RPL bits to 11b (0x3) which typically sets the device to operate
 as a synchronized-spindle master control.
<item>-g: Get and print the current RPL bits and the Rotational Offset byte from
 the device's Geometry Parameters Page.
<item>-o rpl_offset: When clearing (-c) or setting (-m, -M, -s) spindle synchronization
 additionally set the rotational off- set  to  the  given  value. Must be in
 range from 0 to 256. This value is the numerator of a fractional multiplier
 that has 256 as it's denominator (eg a value of 128 indicates a one-half revolution
 skew). A value of zero (0) indicates that rotational offset shall not be used.
</itemize>
<item>SEE ALSO: The mode sense geometry page references in the relevant product
 manual for the disks used in the RaidRunner.
</itemize>


<sect1>SRANKS - set the accessible backend ranks for a controller
<p>
<itemize>
<item>SYNOPSIS: sranks controller_id:ranklist &lsqb;controller_id:ranklist&rsqb;
<item>DESCRIPTION: sranks allows you to set backend rank restrictions, as specified
 by the arguments, for controller on which the command is set. Each argument
 is of the form<tscreen>
<verb>controller_id  the id of the controller (0, 1, ...). 
</verb></tscreen>

ranklist  a comma separated list of rank id's (scsi id's) for which the
 given controller is to have access. sranks will check each argument looking
 for the controller id corresponding to the controller it's running  on and
 set the backend rank access as per the ranklist. Typically,  this  command
  is executed with the output of the BackendRanks GLOBAL environment variable
 at boot time.j

<item>SEE ALSO: environ, pranks
</itemize>


<sect1>STARGD - daemon for SCSI-2 target
<p>
<itemize>
<item>SYNOPSIS: stargd &lsqb;-c&rsqb; &lsqb;-d&rsqb; -m moniker -h hport -s capacity
 &lsqb;-n&rsqb; &lsqb;-r&rsqb; &lsqb;-L cnt&rsqb; &lsqb;-P nprocs&rsqb; &lsqb;-R&rsqb;
 &lsqb;-S sectorsize&rsqb; &lsqb;-nr nrread:nrlen&rsqb; &lsqb;-C&rsqb; &lsqb;-stripesize
 stripesize&rsqb; &lsqb;-irgap nblks&rsqb; &lsqb;-stripe stripe_args&rsqb; device
 id lun store &lsqb;store2&rsqb;
<item>DESCRIPTION: stargd is a daemon process that interprets SCSI-2 commands
 as a &dquot;target&dquot;. &lsqb;In simple SCSI configurations the host computer
 is  a  SCSI  &dquot;initiator&dquot; while  its disk is a SCSI &dquot;target&dquot;.&rsqb;
 stargd usually works closely with a special device (file system) that does
 the hardware interfacing and  message interpretation for a SCSI-2 target (see
 scsihp). When  stargd first starts, it's &dquot;spin state&dquot;, is set to
 indicate that thestore file has yet to &dquot;spin-up&dquot; and hence is NOT
 READY.  This means  that until  the  spin  state is changed to be marked as
 READY (via mstargd &dquot;-o&dquot; option ) all supported SCSI-2 medium-access
 commands will result  in a  CHECK  CONDITION  with the sense key set to &dquot;NOT
 READY&dquot; and additional sense information set to &dquot;LOGICAL UNIT IN
  PROCESS  OF  BECOMMING  READY&dquot; When the spin state is marked as READY
 all supported SCSI-2 medium-access commands are processed correctly. Additional
 NOT READY states can be  set by mstargd's -Z option. 
<item>OPTIONS: stargd  has  3  mandatory  switches,  8 optional switches and
 4 mandatory positional arguments and an optional trailing positional argument.
 The mandatory switches are the -m switch which associates the moniker (i.e
 name) with the raid set that stargd is about to execute on (this provides a
 method of naming raid sets), the -c switch which specifies the capacity of
  the  backend  and the -h switch which advises stargd which controller host
 port it will be communicating  over.   The  4  mandatory  positional arguments
  are  device,  id,  lun and store. The first 3 are concatenated together to
 make the filename of the low level SCSI target device driver. 
<itemize>
<item>The  second  argument  is  the  SCSI  identifier  number this target will
 respond to while the third argument is  the  logical  unit  number  (LUN) within
  that  SCSI identifier which the target represents.  An error will occur during
 daemon  initialization  unless  the  following  files  (with appropriate characteristics)
 are found: <tscreen>
<verb>device/id/lun/cmnd 
</verb></tscreen>
<verb>device/id/lun/data
</verb>

<item>The  fourth  positional  argument  is store. It will typically be a cache
 device although it could be a single disk or a raid level. The trailing optional
 positional argument  is  store2.  If  the  filename store2  can be opened and
 the &dquot;-c&dquot; argument is _not_ given then writes to store are echoed
 to store2.  The SCSI commands that cause writes at  this level  are Write_6
 and Write_10. If store2 cannot be opened (for writing) or the &dquot;-c&dquot;
 argument is given then a warning  message  is  output  during stargd initialization
 and it continues as if store2 had not been given. 
<item>All  switches  may  appear in any order but if present must be before the
 positional arguments. 
<item>The &dquot;-L cnt&dquot; switch indicates that stargd is  to  implement
 a lookahead process for SCSI-2 reads (Read_6 and Read_10) which pre-fetches
 data into the cache based on the last cnt SCSI-2 reads.  The default is a readahead
 of 16 reads (i.e -L 16). The minimum readahead is 2 and the maximum is 63.
 You can specify readahead to be 0 which turns off  all  lookahead. This switch
 can only be used when cache (-c) is being used. The  &dquot;-nr  nread:nrlen&dquot;
  is used to specify 'natural read' information to stargd. Some applications
 may perform reads of a certain  size  which  is greater  than  the  largest
 read the host operating system will allow. In this case, the host operating
 system will break the application's read up into  smaller  reads.  stargd can
 trigger on a certain discontinuous read (by specifying a size in blocks - nread)
 and will prefetch the rest of the application read (nrlen). For
 example, if an application performs a read of 304 blocks on a host operating
 system which has a maximum read size of 128 blocks, then you could set the
 -nr arguments nread:nrlen to 128:304 which will cause stargd to, when it sees
 a discontinuous  read of  size  128 blocks, service the read and also prefectch
 into cache, the next 304 - 128 = 176 blocks of data. See scsihpmtr for analysis
  of host operating system reads. 
<item>The &dquot;-stripesize stripesize&dquot; switch informs stargd the stripe
 size of the raid set which stargd is fronting. If the additional  -C  switch
  toggles whether this value (stripesize) will be used to calculate a cylinder
 size (heads x sectors per track) that ensures that a cylinder is a multiple
 of the given stripe size. If the stripe size is such that there is no multiple
 of heads and sectors that, when multiplied together, is not a  multiple of
 the stripe size, then the default head and sectors per track sizes are used
 - currently 16 head, 128 sectors per track. 
<item>The &dquot;-stripe stripe_args&dquot; switch informs stargd that  a  number
  of  host ports  will  be concurrently accessing this raid set. This switch
 is only usefull when the host based disk access software can  &dquot;stripe&dquot;
  io  to  N different  devices  and each access (read or write) is always less
 than a set stripesize. 
<item>The stripe_args are of the form N:S:I=c.h.l,I=c.h.l, where: N is the number
 of stripes (or host ports) that will be concurrently accessing the raid set,
 S is the stripe size (in 512-byte blocks) that the host will perform i/o in,
 I is an index or &dquot;stripe number&dquot; specifier ranging from 0 to N.
 c.h.l  is the controller, host port, lun  triplet, associated  with  the given
 index. For  example, if we have two host ports and the given stripe-size from
 the host is, say, 1368 blocks, we would then have  the  following  raid:
 set
 additions (in agui form)
 Host Interfaces (2): M 0.0.0 M 0.1.0
 Additional
 stargd args: -stripe 2:1368:0=0.0.0,1=0.1.0


NOTE: that  it  has to be guaranteed that the host stripe software will
 send block 0 (size 1368 or less) to controller, host port, lun  triplet 0.0.0
  and  block  1  (size  1368  or  less) controller, host port, lun triplet 0.1.0,
 block 2 (size 1368 or less) to  controller,  host  port, lun triplet 0.0.0,
 and so forth.

<item>The  &dquot;-C&dquot;  switch  is used to toggle whether stargd calculates
 a cylinder size such that it is a multiple of the given stripe size. The default
  is to calculate a cylinder size based on the given stripe size. 
<item>The  &dquot;-irgap  nblks&dquot;  switch,  specifies  the  inter-read gap,
 nblks, (in blocks). When sequential reads arrive from a host there may  be
  a  small gap  between  successive  reads.  Normally  the  lookahead algorithm
 will ignore these gaps providing they are no larger than the average length
 of the  group  of  sequential  reads that have occurred.  By specifying this
 value, you can increase this gap. This  switch  has  no  meaning  if  the lookahead
 feature is turned off (i.e specifying &dquot;-L 0&dquot;). 
<item>The  &dquot;-R&dquot;  switch  indicates that store should have read-only
 access.  If this switch is NOT present, then the store is assumed to have 
 read-write access. 
<item>The  &dquot;-c&dquot;  switch  indicates that store is a cache (rather
 than a disk or something else remote). This knowledge decreases the number
  of  internal copies  this  daemon  needs to do so it is a performance enhancement.
 The default (i.e. when this switch is not present) is to do  the  extra  copy
 which is the safe course if the exact identity of the store is uncertain. 
<item>The &dquot;-d&dquot; switch is a debug flag. When given the  command  line
  arguments and  other  information  derived during initialization are echoed
 back to standard out and the debug level is set to 1. The debug levels are:
<itemize>
<item>0    no debug messages (default when &dquot;-d&dquot; not given)
<item>1    debug messages on all non-read/write commands
<item>2    debug messages on all commands
</itemize>

Debug messages are typically a single line per command and  are  sent 
 to standard  out. Serious errors are reported to standard error irrespective
 of the current debug level. If the error  is  related  to  incoming  data (from
  the  SCSI  initiator)  then the daemon will continue. If the error cannot
 be recovered from, then the daemon terminates with an  error  message  as its
 exit status.  The debug level can be changed during the execution of a stargd
 daemon by using the &dquot;-d&dquot; option on mstargd.

<item>The &dquot;-m&dquot; switch associates the moniker (i.e name) with the
 raid  set  that stargd  is about to execute on. It provides a method of naming
 raid sets. The moniker can be a maximum of 32 characters. This switch is  mandatory.
 
<item>The &dquot;-h&dquot; switch informs stargd which controller host port it
 will be communicating over. This switch is mandatory. 
<item>The &dquot;-n&dquot; switch toggles statistics being gathered. The default
 action  is to collect statistics. 
<item>The  &dquot;-r&dquot;  switch is for restarting the daemon with as little
 disturbance to the initiator as possible. Usually the SCSI Unit  attention
  condition is  set  on  reset  (and when this daemon commences). When this
 switch is given the daemon starts in the idle state. Use  with  care.  The
  default action (i.e.  when the &dquot;-r&dquot; is not given) is to set a
 SCSI Unit attention condition so that the first SCSI command received will
  have  its  status returned as &dquot;Check condition&dquot; (as required by
 the SCSI-2 standard). 
<item>The  &dquot;-s capacity&dquot; switch informs the daemon what the size
 in blocks this SCSI target will represent. The value for capacity effects 
 the  response this  target makes to the SCSI Read Capacity and Mode Sense (page
 4) commands. This switch is mandatory.  To simplify writing out  large  numbers
 certain suffixes can be used, see suffix. 
<item>The &dquot;-P nprocs&dquot; switch causes the daemon to spawn off nprocs
 copies of it self to allow concurrent processing of SCSI commands. If  not
  specified, the default number of stargd processes created is 4. This value
 can range from 1 to 8 inclusive. The additional processes will not be created
 until the first access from the host port. The  &dquot;-S sectorsize switch
 informs the daemon what sector size, in bytes, this SCSI target will present.
 The value defaults to 512 - the  typical disk  block  size. To simplify writing
 out large numbers certain suffixes can be used, see suffix.
</itemize>
<item>SIGNALS: Two K9 signals are interpreted specially by stargd. 
<itemize>
<item>If the signal K9_SIGINT is received then stargd will check to see whether
 there  is a command in progress and if so terminate it with a &dquot;Check
 condition&dquot; status and set the associated sense  key  to  &dquot;Command
  aborted&dquot;. stargd will then return to its command (waiting) mode.
<item>If  the  signal K9_SIGTERM is received then stargd will do the same as
 it does for K9_SIGINT except it will exit the process rather than  going  to
 command (waiting) mode.
<item>The  SCSI  initiator should interpret a sense key of &dquot;Command aborted&dquot;
 as the target unilaterally aborting a command in progress. The SCSI-2  standard
 suggests the initiator should retry the aborted command.
</itemize>
<item>EXAMPLE:<tscreen>
<verb>stargd -c -s 2M -m RS -h 1 /dev/hostbus/1 6 0 /cache/data
</verb></tscreen>

This line will invoke this daemon and try and open the following files:
<verb>/dev/hostbus/1/6/0/cmnd
</verb>

and
<verb>/dev/hostbus/1/6/0/data
</verb>

The file &dquot;/cache/data&dquot; will be used as store.  The &dquot;-c&dquot;
 switch identifies this file id as a cache to stargd. The &dquot;-s 2M&dquot;
 switch instructs this daemon  to  tell  SCSI  initiators  that  it  is  a 
 1 GigaByte disk (i.e. 2 MegaBlocks).

<item>SUPPORTED SCSI-2 COMMANDS: The table below lists the supported SCSI-2 commands
 (Code and Name) and their action under stargd.
<verb>00: Test Unit Ready  If backend is ready returns GOOD Status, else sets
 Sense Key to Not Ready and returns CHECK CONDITION Status
</verb>
<verb>01: Rezero Unit      Does nothing, returns GOOD Status
</verb>
<verb>03: Request Sense    Sense data held on a per initiator basis (plus extra
 for bad LUN's)
</verb>
<verb>04: Format Unit      Does nothing, returns GOOD Status
</verb>
<verb>07: Reassign Blocks  Consumes data but does nothing, returns GOOD Status
</verb>
<verb>08: Read_6           DPO, FUA and RelAdr not supported
</verb>
<verb>0a: Write_6          DPO, FUA and RelAdr not supported
</verb>
<verb>0b: Seek_6           Does nothing, returns GOOD Status
</verb>
<verb>12: Inquiry          Only standard 36 byte data format supported (not vital
 product data pages)
</verb>
<verb>15: Mode Select      Support pages 1, 2, 3, 4, 8 and 10 (but none writable)
</verb>
<verb>16: Reserve          Doesn't support extents + 3rd parties
</verb>
<verb>17: Release          Doesn't support extents + 3rd parties
</verb>
<verb>1a: Mode Sense       Support pages 1, 2, 3, 4, 8 and 10.
</verb>
<verb>1b  Start Stop       If Start is requested and the Immediate bit is 0 then
 waits for backend to become ready, else does nothing and returns GOOD Status.
 If backend does not become ready within 20 seconds set Sense Key to Not Ready
 and returns CHECK  CONDITION Status
</verb>
<verb>1d  Send Diagnostics Returns GOOD Status when self test else complains
 (does nothing internally)
</verb>
<verb>25  Read Capacity    RelAdr, PMI and logical address &gt; 0 are not supported
</verb>
<verb>28  Read_10          Same as Read_6
</verb>
<verb>2a  Write_10         Same as Write_6
</verb>
<verb>2b  Seek_10          Does nothing, returns GOOD Status
</verb>
<verb>2f  Verify           Does nothing, returns GOOD Status
</verb>
<verb>55  Mode Select_10   Same as Mode Select     
</verb>
<verb>5a  Mode Sense_10    Same as Mode Sense
</verb>
<item>SEE ALSO: scsihp, suffix, mstargd
</itemize>
<sect1>STAT - get status information on the named files (or stdin)
<p>
<itemize>
<item>SYNOPSIS: stat &lsqb;-b&rsqb; &lsqb;file...&rsqb;
<item>DESCRIPTION: stat gets status information on each given  file,  or  the
 standard  input  when a file named `-' is given, and sends it to the standard
 output. For files that are found a line with 6 columns is  output. The meaning
 of each column is summarized below:
<itemize>
<item>1st    filename
<item>2nd    type of file system containing this file
<item>3rd    instance of the containing file system
<item>4th    unique (internal) file identifier
<item>5th    version number of this file
<item>6th    length of this file (in bytes)
</itemize>
<item>If  the  -b  option is given, then the length of each file (6th field)
 is printed  in  512-byte  blocks.  Only  whole blocks  are  reported,  so 
 files  with  lengths less than 512-byte blocks will report is having a block
 size of zero (0).
<item>EXAMPLE
<verb>: raid; stat /bin/ps
</verb>
<verb>ps                               ram    0 0x00049049    2 144
</verb>
<verb>: raid;
</verb>
<item>SEE ALSO: K9getstat, intro
</itemize>
<sect1>STATS - Print cumulative performance statistics on a Raid Set or Cache
 Range
<p>
<itemize>
<item>SYNOPSIS: stats &lsqb;-c cache_moniker&rsqb; &lsqb;-r raid_set&rsqb; &lsqb;-g&rsqb;
 &lsqb;-z&rsqb;
<item>DESCRIPTION: stats is a process that will print and or zero the cumulative
  performance  statistics  which  Raid Set's and Cache Ranges maintain.
<item>OPTIONS:
<itemize>
<item>-c cache_moniker: Zero (-z) and or print (-g) the cache statistics of the
  cache  range  specified by cache_moniker which was set in the add moniker=cache_moniker
 first= ... command (see cache). The  statistics  printed  are  the  number
 of cache hits, cache misses, cache probes per hit and probes per miss. Output
 is in the form
<verb>moniker : hits+misses hits misses hit+miss_probes hit_probes miss_probes
</verb>
<item>r raidset_name: Zero (-z) and or print (-g) the raid set statistics of
 the raid set specified by raidset_name. When printing (-g) statistics, for
 each backend  in the  raid  set,  the  cumulative  number  of reads, writes,
 raid failures and write  failures  to  that backend are printed. Output is
 in the form
<verb>D0 r0_cnt r0_fails w0_cnt w0_fails; D1 r1_cnt r1_fails w1_cnt w1_fails;
 D...;
</verb>
</itemize>
<item>GENERAL: When  gathering (or zeroing) a Cache Range's statistics, a special
 system call to the RaidRunners cache is made. When gathering (or zeroing) a
  Raid  Set's  statistics,  a read  or  write (of the control string &dquot;zerostats&dquot;
 is made to the raid_bind_point/stats control file.
<item>SEE ALSO: cache, raid0, raid1, raid3, raid5
</itemize>
<sect1>STRING - perform a string operation on a given value
<p>
<itemize>
<item>SYNOPSIS: string option value
<item>DESCRIPTION: string  provides  various  string  type  operations on the
 given value which is treated  as  a  string.  Options  are length, range and
 split.
<item>OPTIONS:
<itemize>
<item>length string: The  length option returns the number of characters in the
 given string.
<item>range string first last: The range option returns  the  substring  from
  the given string that lies between the indices given by first and last.  An
 index of 0 refers to the  first character  in  the  string.  If  last is beyond
 the length of the string, then it becomes the index  of the  last character
 in the string. If first is less than last then the  substring  is  extracted
  backwards.
<item>split string split_ch: The  split  option  will replace each occurrence
 of the character split_ch in the given string  with  a space.
</itemize>
<item>EXAMPLES: Some simple examples:
<verb>set string ABCDEFGHIJ              &num; create the string
</verb>
<verb>set subs `string length &dollar;string'   &num; get it's length
</verb>
<verb>echo &dollar;subs
</verb>
<verb>10
</verb>
<verb>set subs `string range &dollar;string 2 2'     &num; extract character
 at index 3
</verb>
<verb>echo &dollar;subs
</verb>
<verb>C
</verb>
<verb>set subs `string range &dollar;string 3 6'     &num; extract from indices
 3 to 6
</verb>
<verb>echo &dollar;subs
</verb>
<verb>DEFG
</verb>
<verb>set subs `string range &dollar;string 6 3'     &num; backwards
</verb>
<verb>echo &dollar;subs
</verb>
<verb>GFED
</verb>
<verb>set subs `string range &dollar;string 4 70'    &num; extract from index
 4 to 70 (or end)
</verb>
<verb>echo &dollar;subs
</verb>
<verb>EFGHIJ
</verb>
<verb>set string D1,D2,D4,D8             &num; create the string
</verb>
<verb>set subs `string split &dollar;string ,'  &num; split the string
</verb>
<verb>echo &dollar;subs
</verb>
<verb>D1 D2 D4 D8 
</verb>
</itemize>

<sect1>SUFFIX - Suffixes permitted on some big decimal numbers
<p>
<itemize>
<item>DESCRIPTION: In some commands  that can take big decimal numbers as arguments
 certain suffixes are allowed. The suffix is a single alphabetical character
 that must follow immediately after the decimal number it is qualifying. The
 alphabetical character may be upper or lower case. Negative numbers cannot
 have suffixes.

The accepted suffixes are:
<itemize>
<item>w: multiply number by 2
<item>b: multiply number by 512
<item>k: multiply number by 1024
<item>m: multiply number by 1048576
<item>g: multiply number by 1073741824
</itemize>

The  resulting  number  must fit in a 32 bit unsigned number which means
 &dquot;3G&dquot; can be represented (== 3,221,225,472) but &dquot;4G&dquot;
 cannot. &dquot;0G&dquot; is allowable and is interpreted as zero.
</itemize>
<itemize>
<item>COMMANDS USING SUFFIXES: dd, stargd
</itemize>
<sect1>SYSLOG - device to send system messages for logging
<p>
<itemize>
<item>SYNOPSIS: bind -k syslog bind_point
<item>DESCRIPTION: The  syslog file system provides user level entry of messages
 into the system logging facility (see syslogd). Writes to this device will
 be time-stamped and stored with a message class of  &dquot;NOTICE&dquot;  in
  the  system log. Reads from this device will return EOF. By default the system
 logging device is bound at /dev/syslog.
<item>EXAMPLE:<tscreen>
<verb>&gt; /dev/syslog
</verb></tscreen>
<verb>bind -k syslog /dev/syslog
</verb>
<verb>ls -l /dev/syslog
</verb>
<verb>/dev/syslog                   syslog    0 0x00000000    0 0
</verb>
<verb>echo &lcub;Some important message&rcub; &gt; /dev/syslog
</verb>
<verb>syslogd
</verb>
<verb>1: INFO: RaidRunner Syslog Boot
</verb>
<verb>10: NOTICE: Some important message
</verb>
<item>SEE ALSO: syslogd
</itemize>


<sect1>SYSLOGD - initialize or access messages in the system log area
<p>
<itemize>
<item>SYNOPSIS: syslogd &lsqb;-I&rsqb; &lsqb;-p cnt&rsqb;
<item>DESCRIPTION: syslogd either initialize the system message logging area
 or print stored messages from that area.
<item>OPTIONS:
<item>-I: Initialize  the  system  message logging area. This command is usually
 executed at boot time and is not normally invoked by the user.
<item>-p cnt: Print the last cnt messages stored in the system message logging
 area.  /nr This is the default  if  no options are given and cnt is set to
 20.

Messages are printed in the format -
<verb>timestamp: message class: message
</verb>

where timestamp is  the time the message was logged recorded as the number
 of seconds from the time the RaidRunner was booted, message class is the type
 of message logged indication the importance (or class) of the message. message
 is the message itself

<item>MESSAGE CLASS

There are currently nine (9) message classes
</itemize>
<enum>
<item>EMERG: messages of an extremely serious nature from which the RaidRunner
 cannot recover
<item>ALERT: messages of a serious nature from which the RaidRunner can only
 partially recover
<item>CRIT: messages of a serious nature from which the RaidRunner can almost
 fully recover
<item>ERR: messages indicating internal errors
<item>WARNING: messages of a serious from which the RaidRunner can fully recover,
 for example automatic allocation  of hot spare to Raid 1, 3 or 5 file system.
<item>NOTICE :messages logged via writes to syslog device
<item>INFO: informative messages
<item>DEBUG: debugging messages options are given and cnt is set to 20.
<item>REPEATS: Indicates that the previous message has been repeated N times
 every S seconds since it's initial entry.
</enum>
<itemize>
<item>SYSLOG OUTPUT: When messages are logged, they are stored in the system
 message logging area.  If the global environment variable,  SYSLOG_CONF, is
 set to a value of 'C' or is not set at all then messages will be printed to
 the console as well. If the message has a suffix of RPT N/S then this message
 has been logged N times every S  seconds  since  it's initial entry into the
 system message logging area.
<item>SEE ALSO: syslog, setenv
</itemize>
<sect1>TEST - condition evaluation command
<p>
<itemize>
<item>SYNOPSIS: test expr 
<item>DESCRIPTION: test  evaluates  the expr and if its value is true then it
 returns a K9 status of NIL  which  is  equivalent  to  the true command. Alternatively
 if test evaluates the expr and if its value is false then it returns a K9 
 status  of &dquot;false&dquot; which is equivalent to the false command. If
  no  arguments are given then a K9 status of &dquot;false&dquot; is returned.
  If the expression doesn't obey the syntax given below  then  an error message
 is written to standard error and returned as the K9 status. Note that  any
  non-NIL  K9 status  is  interpreted  as  false  by husky condition logic (e.g.
 &dquot;if&dquot;). The basic expressions use by test fall into 3  categories:
 file  tests,  string  tests and numeric tests. These basic expressions  can
  be  modified  or  combined  into  larger expressions by a 4th category called
 operators.
<item>FILE TESTS: The following file tests are supported:
<itemize>
<item>-d file: True if file exists and is a directory.
<item>-f file: True if file exists.
<item>-s file: True if file exists and is non-zero length.
</itemize>
<item>STRING TESTS: The command &dquot;test &lcub;&rcub;&dquot; is syntactically
 correct and has the value &dquot;false&dquot; because &dquot;&lcub;&rcub;&dquot;
 is an empty string. The command &dquot;test&dquot; by itself has the value
 &dquot;false&dquot;. The commands &dquot;test hello&dquot; and &dquot;test
 -z&dquot; both have the value &dquot;true&dquot;. The following string tests
 are supported:
<itemize>
<item>-n str: True if the length of str is non-zero.
<item>-z str: True if the length of str is zero.
<item>str1 = str2: True if str1 and str2 are identical. Spaces surrounding &dquot;=&dquot;
 are required.
<item>str1 != str2: True if str1 and str2 are not identical. Spaces surrounding
 &dquot;!=&dquot; are required.
<item>str: True if str is not a null (empty) string
</itemize>
<item>NUMERIC TESTS: These numeric arguments are evaluated as signed  integers.
 Currently  an  internal  32  bit integer representation is used  limiting 
 the   range   of   valid   integers   from -2,147,483,648  to  2,147,483,647
  (inclusive). Thus fixed point and floating point numbers cannot be  compared.
  The spaces  surrounding  the  numeric  comparison tokens (e.g. &dquot;-eq&dquot;)
 are required. Instead of a number an expression of the form &dquot;-l str&dquot;
 can be  given.  This  evaluates to the number of characters in the string str.
 The following numeric tests are supported:
<itemize>
<item>n1 -eq n2: True if n1 and n2 are numerically equal
<item>n1 -ge n2: True if n1 is greater than or equal to n2
<item>n1 -gt n2: True if n1 is greater than n2
<item>n1 -le n2: True if n1 is less than or equal to n2
<item>n1 -lt n2: True if n1 is less than n2
<item>n1 -ne n2: True if n1 is not equal to n2
</itemize>
<item>OPERATORS: The following operators are supported:
<itemize>
<item>!: Unary negation operator. Appears to the left of the expression it is
 negating.
<item>-a: Binary AND operator. Appears between the 2 expressions it is logically
 combining.
<item>-o: Binary OR operator. Appears between the 2 expressions it is logically
 combining.
<item>( expr ): Parentheses are used to group expressions. Since parentheses
 are husky special characters they need to be quoted or escaped.
<item>The relative precedence of these operators  from  high  to low is: () !
 -a -o.  Thus the expression:<tscreen>
<verb>test ! -f /bin/ls -a -d /env
</verb></tscreen>
</itemize>

is the same as:
<verb>test &lcub;(&rcub; ! -f /bin/ls &lcub;)&rcub; -a -d /env
</verb>


The  &dquot;!&dquot; operator should appear to the left of other unary
 operators. Basic binary operators have  higher  precedence than &dquot;-a&dquot;
 and &dquot;-o&dquot;.

<item>SEE ALSO: husky 
</itemize>


<sect1>TIME - Print the number of seconds since boot (or reset of clock)
<p>
<itemize>
<item>SYNOPSIS: time
<item>DESCRIPTION: time will print the time in seconds since  the  RaidRunner
 was booted or since the clock was last reset.
</itemize>
<sect1>TRAP - intercept a signal and perform some action
<p>
<itemize>
<item>SYNOPSIS:
<itemize>
<item>trap
<item>trap n ...
<item>trap &lcub;&rcub; n ...
<item>trap arg n ...
</itemize>
<item>DESCRIPTION: trap  allows signals directed at this process to intercept
 signals and potentially take  some  special  action.  When trap  is  used 
 with  no  arguments then all current (non- default) traps for this process
 are printed. When the first argument is a number  (optionally  followed by
  other  numbers)  then  this number is interpreted as a signal number whose
 action is to be set to the default for that  signal (extra numbers are treated
 in a similar fashion). When the first argument is an empty string (i.e. &lcub;&rcub;)
  then the   signals  nominated  by  the  following  numbers  are ignored. When
 the first argument is a non-empty string then if  the signals  nominated  by
  the  following numbers occur, then &dquot;arg&dquot; will be executed. N.B.
 Signal number 4 (kill)  can  be  neither  caught  nor ignored.

The following table maps signal numbers to an explanation:
<item>0      unused signal
<item>1      hangup
<item>2      interrupt (rubout)
<item>3      quit (ASCII FS)
<item>4      kill (cannot be caught or ignored)
<item>5      write on a pipe with no one to read it
<item>6      alarm clock
<item>7      software termination signal
<item>8      child process has changed state
<item>9      process could not obtain memory (from heap)
</itemize>
<itemize>
<item>SEE ALSO: kill
</itemize>
<sect1>TRUE - returns the K9 true status
<p>
<itemize>
<item>SYNOPSIS: true
<item>DESCRIPTION: true does nothing other than return the K9 true status. K9
 processes return a pointer to a C string (null  terminated array  of  characters)
  on termination. If that pointer is NULL then a true exit value is  assumed
  while  all  other returned pointer values are interpreted as false (with the
 string being some explanation of what went wrong). This command returns a NULL
 pointer value  as  its  return value.   Returning  a  NULL  pointer  value
  is  sometimes referred to as returning NIL. The husky shell interprets the
 token &dquot;:&dquot; to have the  same meaning as true.
<item>SEE ALSO: false
</itemize>
<sect1>STTY or TTY - print the user's terminal mount point or terminfo status
<p>
<itemize>
<item>SYNOPSIS:
<itemize>
<item>tty
<item>stty &lsqb;ttyname&rsqb;
</itemize>
<item>DESCRIPTION: tty examines the device on which the it is running, and if
 the  device  is  on  a  DUART, then the mount point of the device is printed.
 If the device is not a DUART,  then  an appropriate message is printed.

stty  prints the terminfo structure associated with either the terminal
 device that stty is being  executed  from  or the  given terminal device -
 ttyname. If an invalid device name is given or the device stty is being executed
 from is not  a DUART, an appropriate message is printed. This command is mainly
 useful for debugging the RaidRunner kernel.
</itemize>
<itemize>
<item>RETURN STATUS: On  success  a  return  code  of  0 is returned, else 1
 is returned.
</itemize>
<sect1>UNSET - delete one or more environment variables
<p>
<itemize>
<item>SYNOPSIS
<itemize>
<item>unset name
<item>unset name name ...
</itemize>
<item>DESCRIPTION: unset removes the given environment variable(s). This is done
 by removing the given variable(s) from the /env file system.
<item>SEE ALSO: set, env
</itemize>
<sect1>UNSETENV - unset (delete) a GLOBAL environment variable
<p>
<itemize>
<item>SYNOPSIS: unsetenv name &lsqb;name ...&rsqb;
<item>DESCRIPTION: unsetenv  deletes  the  GLOBAL  environment  variable name
 along with it's contents. If multiple names are given, then each GLOBAL  environment
 variable is deleted. If the given name is not  GLOBAL environment variable
 then nothing is done and no error status is set.
<item>NOTE: A GLOBAL environment variable is one which is stored in  a non volatile
 area on the RaidRunner and hence is available between successive power cycles
 or  reboots.  These  variables ARE NOT the same as husky environment variables.
 The non volatile area is co-located  with  the  RaidRunner Configuration area.
<item>SEE ALSO: printenv, setenv, rconf
</itemize>
<sect1>VERSION - print out the version of the RaidRunner kernel
<p>
<itemize>
<item>SYNOPSIS: version
<item>DESCRIPTION: version  prints out the version of the RaidRunner code which
 comprises the version number, date of creation and creator.
</itemize>
<sect1>WAIT - wait for a process (or my children) to terminate
<p>
<itemize>
<item>SYNOPSIS: wait &lsqb;pid&rsqb;
<item>DESCRIPTION: wait  either  waits for the given pid (process identifier)
 to terminate or, if no argument is given,  waits  for  all the children of
 this process to terminate. When  a  pid is given then the exit status of that
 process is returned by this command. When no  pid  is  given  then this  command
 returns a NIL status (when all children have terminated).
<item>SEE ALSO: K9wait, K9kill
</itemize>
<sect1>WARBLE - periodically pulse the buzzer
<p>
<itemize>
<item>SYNOPSIS: warble period count
<item>DESCRIPTION: warble will save the current state of the buzzer (on or off),
 then turn the buzzer on for period milliseconds, then off for period/2 and
 repeat this for count times. 
<item>SEE ALSO: buzzer, sos
</itemize>
<sect1>XD- dump given file(s) in hexa-decimal to standard out
<p>
<itemize>
<item>SYNOPSIS: xd &lsqb; file ... &rsqb;
<item>DESCRIPTION: xd dumps each given file in hexadecimal format to standard
 out.  If no file is given (or it is &dquot;-&dquot;) then standard  in is used.
</itemize>
<sect1>ZAP - write zeros to a file
<p>

SYNOPSIS: zap &lsqb;-b blockSize&rsqb; &lsqb;-f byteVal&rsqb; count offset
 &lt;&gt;&lsqb;3&rsqb; store

DESCRIPTION: zap  writes  count  * 8192 bytes of zeros at byte position
 offset * 8192 into file store (which is opened and associated  with  file 
 descriptor 3). Both count and offset may have a suffix. The optional &dquot;-b&dquot;
 switch allows the block size to  be  set to  blockSize bytes. The default block
 size is 8192 bytes. The optional &dquot;-f&dquot; switch allows the fill character
  to  be set  to byteVal which should be a number in the range 0 to 255 (inclusive).
 The default fill  character  is  0  (i.e. zero). Every  100  write  operations
  the current count is output (usually overwriting the previous count output).
 Errors on the write operations are ignored.

SEE ALSO: suffix
<sect1>ZCACHE - Manipulate  the zone optimization IO table of a Raid Set's cache
<p>
<itemize>
<item>SYNOPSIS: zcache -c cache_moniker &lsqb;-E extents&rsqb; &lsqb;-P portion&rsqb;
 &lsqb;-W 0|1&rsqb; &lsqb;-p&rsqb;
<item>DESCRIPTION: zcache is a utility that will print and or modify the zone
 optimized IO table of a given cache range.
<item>OPTIONS:
<itemize>
<item>-c cache_moniker: Specify the cache range,  cache_moniker,  to  print the
 zone table or modify it's contents. cache_moniker, is the name which was set
 in the add moniker=cache_moniker first= ... command  (see cache). If no other
 options are given the zone table is printed. When the zone table is printed
 it is in the form of
<verb>n state z1_lo..z1_hi@z1_blks z2_lo..z2_hi@z2_blks ... zn_lo..zn_hi@zn_blks
</verb>
<item>where n is the number of IO optimized zones, state  is  either &dquot;on&dquot;
 for zone optimized IO, &dquot;off&dquot; for no zone optimized IO or &dquot;none&dquot;
 if no zones are available. z1_lo..z1_hi@z1_blks ...  zn_lo..zn_hi@zn_blks 
 lists  the starting  and  ending blocks and the optimized block count for each
 zone.
<item>-E extents: Specify the number of data drives in the  Raid  Set for which
 the cache range exists.
<item>-P portion: Specify  the  percentage,  limited to be between 50 and 300,
 that the optimized block  count  for  each zone  is  to  be  adjusted. That
 is, if you need to reduce the optimized block count for each  zone  by say
 10&percnt; you would set portion to 90.
<item>-W 0|1: Turn  on  (1)  or off (0) zone IO optimizations for the given cache
 range.
</itemize>
<item>SEE ALSO: cache
</itemize>


<sect1>ZERO - file when read yields zeros continuously
<p>
<itemize>
<item>SYNOPSIS: bind -k &lcub;zero &lsqb; &num; &rsqb;&rcub; bind_point
<item>DESCRIPTION: zero is a special file that when written to is an infinite
 sink of data (i.e. anything can be written to it and it will be disposed of
 quickly). When zero is read it is an infinite source of  zeros  (i.e.  the
 byte value 0). The zero file will appear in the K9 namespace at the bind_point.
 If  the  optional &dquot;&num;&dquot; is given then the zero file still is
 an infinite sink of data. However, when read, each 512 bytes is viewed as a
 block (starting at block 0 at the beginning of the file). Each block  contains
  128  4  byte integers (&dquot;unsigned long&dquot; in C) each of which contain
 the current block number. This option is meant as a debugging aid.
<item>EXAMPLE: Husky installs a zero special file as follows:<tscreen>
<verb>bind -k zero /dev/zero
</verb></tscreen>
Example of use to make 32 Kilobyte file (called &dquot;/fill&dquot;) full
 of zeros.
<verb>dd if=/dev/zero of=/fill bs=8k count=4
</verb>
<item>SEE ALSO: null, log
</itemize>

<sect1>ZLABELS - Write zeros to the front and end of Raid Sets
<p>
<itemize>
<item>SYNOPSIS
<itemize>
<item>zlabels -a
<item>zlabels raidset &lsqb;raidset .... &rsqb;
</itemize>
<item>DESCRIPTION: zlabels  is  a husky script which writes zeros to both the
 front and end of either all configured raid sets or to given raid sets. Typically
 a host operating system will write label(s) onto a disk. Nearly all operating
 systems write a  few  blocks at the start of a disk and some write copies at
 the end of the disk as well. As this label contains formatting and modified
 disk geometry  information a change to a raid set that effects the geometry
 of it's offered disk drive will conflict with any labels  written before. zlabels
 writes zero's at the start of a raid set and also at the end. The  number of
 blocks zeroed is dependant on the raid set type and io chunksize. Typically
 50 io chunk size blocks are written at the start and  49 at the end. In the
 case of a raid type 3, the number of data drives times 50 (and 49) are written.
<item>OPTIONS :
<itemize>
<item>-a: All configured raid sets will be zeroed.
<item>raidset: The named raid set, or raid sets, are zeroed.
</itemize>
<item>SEE ALSO: dd
</itemize>
<sect>Advanced Topics: SCSI Monitor Daemon (SMON)
<p>

Another way of communicating with the onboard controller from the host
 operating system is using the SCSI Monitor (SMON) facility. SMON provides an
 ASCII communication channel on an assigned SCSI ID and LUN. The commands discussed
 in section 7 may also be issued over this channel to manipulate the RAID configuration
 and operation. This mechanism is utilized under Solaris to provide a communication
 channel between an X Based GUI and the RAID controller. It is currently un-utilized
 under Linux. See the description of the smon daemon in the 5070 command reference
 above.
<sect>Further Reading
<p>
<itemize>
<item>The Linux software-RAID-HOWTO by Linas Vepstas
<item>The Plan9 pages at AT&amp;T Bell Labs: http://plan9.bell-labs.com/plan9/index.htm
 
</itemize>

</article>