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: src/share/man/man4/ses.4,v 1.2.2.6 2001/08/17 13:08:39 ru Exp $
  27 .\" $DragonFly: src/share/man/man4/ses.4,v 1.3 2006/05/26 19:39:39 swildner Exp $
  28 .\"
  29 .Dd January 29, 2000
  30 .Dt SES 4
  31 .Os
  32 .Sh NAME
  33 .Nm ses
  34 .Nd SCSI Environmental Services driver
  35 .Sh SYNOPSIS
  36 .Cd device ses
  37 .Sh DESCRIPTION
  38 The
  39 .Nm
  40 driver provides support for all
  41 .Tn SCSI
  42 devices of the environmental services class that are attached to the system
  43 through a supported
  44 .Tn SCSI
  45 Host Adapter, as well as emulated support for SAF-TE (SCSI Accessible
  46 Fault Tolerant Enclosures).
  47 The environmental services class generally are enclosure devices that
  48 provide environmental information such as number of power supplies (and
  49 state), temperature, device slots, and so on.
  50 .Pp
  51 A
  52 .Tn SCSI
  53 Host
  54 adapter must also be separately configured into the system
  55 before a
  56 .Tn SCSI
  57 Environmental Services device can be configured.
  58 .Sh KERNEL CONFIGURATION
  59 It is only necessary to explicitly configure one
  60 .Nm
  61 device; data structures are dynamically allocated as devices are found
  62 on the
  63 .Tn SCSI
  64 bus.
  65 .Pp
  66 A separate option,
  67 .Va SES_ENABLE_PASSTHROUGH ,
  68 may be specified to allow the
  69 .Nm
  70 driver to perform functions on devices of other classes that claim to
  71 also support
  72 .Nm
  73 functionality.
  74 .Sh IOCTLS
  75 The following
  76 .Xr ioctl 2
  77 calls apply to
  78 .Nm
  79 devices.
  80 They are defined in the header file
  81 .In bus/cam/scsi/scsi_ses.h
  82 (\fIq.v.\fR).
  83 .Pp
  84 .Bl -tag -width SESIOC_GETENCSTAT
  85 .It Dv SESIOC_GETNOBJ
  86 Used to find out how many
  87 .Nm
  88 objects are driven by this particular device instance.
  89 .It Dv SESIOC_GETOBJMAP
  90 Read, from the kernel, an array of SES objects which contains
  91 the object identifier, which subenclosure it is in, and the
  92 .Nm
  93 type of the object.
  94 .It Dv SESIOC_GETENCSTAT
  95 Get the overall enclosure status.
  96 .It Dv SESIOC_SETENCSTAT
  97 Set the overall enclosure status.
  98 .It Dv SESIOC_GETOBJSTAT
  99 Get the status of a particular object.
 100 .It Dv SESIOC_SETOBJSTAT
 101 Set the status of a particular object.
 102 .It Dv SESIOC_GETTEXT
 103 Get the associated help text for an object (not yet implemented).
 104 .Nm
 105 devices often have descriptive text for an object which can tell
 106 you things like location (e.g, "left power supply").
 107 .It Dv SESIOC_INIT
 108 Initialize the enclosure.
 109 .El
 110 .Sh EXAMPLE USAGE
 111 The files contained in
 112 .Aq Pa usr/share/examples/ses
 113 show simple mechanisms for how to use these interfaces, as well as a
 114 very stupid simple monitoring daemon.
 115 .Sh FILES
 116 .Bl -tag -width /dev/rsdXXXXX -compact
 117 .It Pa /dev/ses Ns Ar N
 118 The
 119 .Em Nth
 120 .Nm SES
 121 device.
 122 .El
 123 .Sh DIAGNOSTICS
 124 When the kernel is configured with
 125 .Tn DEBUG
 126 enabled, the first open to an SES device will spit out overall enclosure
 127 parameters to the console.
 128 .Sh HISTORY
 129 The
 130 .Nm
 131 driver was written for the
 132 .Tn CAM
 133 .Tn SCSI
 134 subsystem by Matthew Jacob.
 135 This is a functional equivalent of a similar
 136 driver available in Solaris, Release 7.