/share/man/man4/ses.4

  1.\" Copyright (c) 2000
  2.\"	Matthew Jacob <mjacob@FreeBSD.org>.  All rights reserved.
  3.\"
  4.\" Redistribution and use in source and binary forms, with or without
  5.\" modification, are permitted provided that the following conditions
  6.\" are met:
  7.\" 1. Redistributions of source code must retain the above copyright
  8.\"    notice, this list of conditions and the following disclaimer.
  9.\"
 10.\" 2. Redistributions in binary form must reproduce the above copyright
 11.\"    notice, this list of conditions and the following disclaimer in the
 12.\"    documentation and/or other materials provided with the distribution.
 13.\"
 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 24.\" SUCH DAMAGE.
 25.\"
 26.\" $FreeBSD$
 27.\"
 28.Dd January 29, 2000
 29.Dt SES 4
 30.Os
 31.Sh NAME
 32.Nm ses
 33.Nd SCSI Environmental Services driver
 34.Sh SYNOPSIS
 35.Cd device ses
 36.Sh DESCRIPTION
 37The
 38.Nm
 39driver provides support for all
 40.Tn SCSI
 41devices of the environmental services class that are attached to the system
 42through a supported
 43.Tn SCSI
 44Host Adapter, as well as emulated support for SAF-TE (SCSI Accessible
 45Fault Tolerant Enclosures).
 46The environmental services class generally are enclosure devices that
 47provide environmental information such as number of power supplies (and
 48state), temperature, device slots, and so on.
 49.Pp
 50A
 51.Tn SCSI
 52Host
 53adapter must also be separately configured into the system
 54before a
 55.Tn SCSI
 56Environmental Services device can be configured.
 57.Sh KERNEL CONFIGURATION
 58It is only necessary to explicitly configure one
 59.Nm
 60device; data structures are dynamically allocated as devices are found
 61on the
 62.Tn SCSI
 63bus.
 64.Pp
 65A separate option,
 66.Va SES_ENABLE_PASSTHROUGH ,
 67may be specified to allow the
 68.Nm
 69driver to perform functions on devices of other classes that claim to
 70also support
 71.Nm
 72functionality.
 73.Sh IOCTLS
 74The following
 75.Xr ioctl 2
 76calls apply to
 77.Nm
 78devices.
 79They are defined in the header file
 80.In cam/scsi/scsi_ses.h
 81(\fIq.v.\fR).
 82.Bl -tag -width SESIOC_GETENCSTAT
 83.It Dv SESIOC_GETNOBJ
 84Used to find out how many
 85.Nm
 86objects are driven by this particular device instance.
 87.It Dv SESIOC_GETOBJMAP
 88Read, from the kernel, an array of SES objects which contains
 89the object identifier, which subenclosure it is in, and the
 90.Nm
 91type of the object.
 92.It Dv SESIOC_GETENCSTAT
 93Get the overall enclosure status.
 94.It Dv SESIOC_SETENCSTAT
 95Set the overall enclosure status.
 96.It Dv SESIOC_GETOBJSTAT
 97Get the status of a particular object.
 98.It Dv SESIOC_SETOBJSTAT
 99Set the status of a particular object.
100.It Dv SESIOC_GETTEXT
101Get the associated help text for an object (not yet implemented).
102.Nm
103devices often have descriptive text for an object which can tell
104you things like location (e.g., "left power supply").
105.It Dv SESIOC_INIT
106Initialize the enclosure.
107.El
108.Sh EXAMPLE USAGE
109The files contained in
110.In usr/share/examples/ses
111show simple mechanisms for how to use these interfaces, as well as a
112very stupid simple monitoring daemon.
113.Sh FILES
114.Bl -tag -width /dev/rsdXXXXX -compact
115.It Pa /dev/ses Ns Ar N
116The
117.Em Nth
118.Nm SES
119device.
120.El
121.Sh DIAGNOSTICS
122When the kernel is configured with
123.Tn DEBUG
124enabled, the first open to an SES device will spit out overall enclosure
125parameters to the console.
126.Sh HISTORY
127The
128.Nm
129driver was written for the
130.Tn CAM
131.Tn SCSI
132subsystem by Matthew Jacob.
133This is a functional equivalent of a similar
134driver available in Solaris, Release 7.