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 .Dd November 12, 2019
  27 .Dt SES 4
  28 .Os
  29 .Sh NAME
  30 .Nm ses
  31 .Nd SCSI Environmental Services driver
  32 .Sh SYNOPSIS
  33 .Cd device ses
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 driver provides support for all
  38 .Tn SCSI
  39 devices of the environmental services class that are attached to the system
  40 through a supported
  41 .Tn SCSI
  42 Host Adapter, as well as emulated support for SAF-TE (SCSI Accessible
  43 Fault Tolerant Enclosures).
  44 The environmental services class generally are enclosure devices that
  45 provide environmental information such as number of power supplies (and
  46 state), temperature, device slots, and so on.
  47 .Pp
  48 A
  49 .Tn SCSI
  50 Host
  51 adapter must also be separately configured into the system
  52 before a
  53 .Tn SCSI
  54 Environmental Services device can be configured.
  55 .Sh KERNEL CONFIGURATION
  56 It is only necessary to explicitly configure one
  57 .Nm
  58 device; data structures are dynamically allocated as devices are found
  59 on the
  60 .Tn SCSI
  61 bus.
  62 .Pp
  63 A separate option,
  64 .Va SES_ENABLE_PASSTHROUGH ,
  65 may be specified to allow the
  66 .Nm
  67 driver to perform functions on devices of other classes that claim to
  68 also support
  69 .Nm
  70 functionality.
  71 .Sh IOCTLS
  72 The following
  73 .Xr ioctl 2
  74 calls apply to
  75 .Nm
  76 devices.
  77 They are defined in the header file
  78 .In cam/scsi/scsi_enc.h
  79 (\fIq.v.\fR).
  80 .Bl -tag -width ENCIOC_GETENCSTAT
  81 .It Dv ENCIOC_GETNELM
  82 Used to find out how many
  83 .Nm
  84 elements are driven by this particular device instance.
  85 .It Dv ENCIOC_GETELMMAP
  86 Read, from the kernel, an array of SES elements which contains
  87 the element identifier, which subenclosure it is in, and the
  88 .Nm
  89 type of the element.
  90 .It Dv ENCIOC_GETENCSTAT
  91 Get the overall enclosure status.
  92 .It Dv ENCIOC_SETENCSTAT
  93 Set the overall enclosure status.
  94 .It Dv ENCIOC_GETELMSTAT
  95 Get the status of a particular element.
  96 .It Dv ENCIOC_SETELMSTAT
  97 Set the status of a particular element.
  98 .It Dv ENCIOC_GETTEXT
  99 Get the associated help text for an element (not yet implemented).
 100 .Nm
 101 devices often have descriptive text for an element which can tell
 102 you things like location (e.g., "left power supply").
 103 .It Dv ENCIOC_INIT
 104 Initialize the enclosure.
 105 .It Dv ENCIOC_GETELMDESC
 106 Get the element's descriptor string.
 107 .It Dv ENCIOC_GETELMDEVNAMES
 108 Get the device names, if any, associated with this element.
 109 .It Dv ENCIOC_GETSTRING
 110 Used to read the SES String In Diagnostic Page.
 111 The contents of this page are device-specific.
 112 .It Dv ENCIOC_SETSTRING
 113 Used to set the SES String Out Diagnostic Page.
 114 The contents of this page are device-specific.
 115 .It Dv ENCIOC_GETENCNAME
 116 Used to get the name of the enclosure.
 117 .It Dv ENCIOC_GETENCID
 118 Used to get the Enclosure Logical Identifier.
 119 .El
 120 .Sh EXAMPLE USAGE
 121 The files contained in
 122 .In /usr/share/examples/ses
 123 show simple mechanisms for how to use these interfaces, as well as a
 124 very stupid simple monitoring daemon.
 125 .Sh FILES
 126 .Bl -tag -width /dev/rsdXXXXX -compact
 127 .It Pa /dev/ses Ns Ar N
 128 The
 129 .Em Nth
 130 .Nm SES
 131 device.
 132 .El
 133 .Sh DIAGNOSTICS
 134 When the kernel is configured with
 135 .Tn DEBUG
 136 enabled, the first open to an SES device will spit out overall enclosure
 137 parameters to the console.
 138 .Sh SEE ALSO
 139 .Xr sesutil 8
 140 .Sh HISTORY
 141 The
 142 .Nm
 143 driver was originally written for the
 144 .Tn CAM
 145 .Tn SCSI
 146 subsystem by Matthew Jacob and first released in
 147 .Fx 4.3 .
 148 It was a functional equivalent of a similar
 149 driver available in Solaris, Release 7.
 150 It was largely rewritten by Alexander Motin, Justin Gibbs, and Will Andrews for
 151 .Fx 9.2 .