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: head/share/man/man4/ses.4 70466 2000-12-29 09:18:45Z ru $
27.\"
28.Dd January 29, 2000
29.Dt SES 4
30.Os FreeBSD
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
56SCSI Environmental 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.Aq Pa cam/scsi/scsi_ses.h
81(\fIq.v.\fR).
82.Pp
83.Bl -tag -width SESIOC_GETENCSTAT
84.It Dv SESIOC_GETNOBJ
85Used to find out how many
86.Nm
87objects are driven by this particular device instance.
88.It Dv SESIOC_GETOBJMAP
89Read, from the kernel, an array of SES objects which contains
90the object identifier, which subenclosure it is in, and the
91.Nm
92type of the object.
93.It Dv SESIOC_GETENCSTAT
94Get the overall enclosure status.
95.It Dv SESIOC_SETENCSTAT
96Set the overall enclosure status.
97.It Dv SESIOC_GETOBJSTAT
98Get the status of a particular object.
99.It Dv SESIOC_SETOBJSTAT
100Set the status of a particular object.
101.It Dv SESIOC_GETTEXT
102Get the associated help text for an object (not yet implemented).
103.Nm
104devices often have descriptive text for an object which can tell
105you things like location (e.g, "left power supply").
106.It Dv SESIOC_INIT
107Initialize the enclosure.
108.El
109.Sh EXAMPLE USAGE
110The files contained in
111.Aq Pa usr/share/examples/ses
112show simple mechanisms for how to use these interfaces, as well as a
113very stupid simple monitoring daemon.
114.Sh FILES
115.Bl -tag -width /dev/rsdXXXXX -compact
116.It Pa /dev/ses Ns Ar N
117The
118.Em Nth
119.Nm SES
120device.
121.El
122.Sh DIAGNOSTICS
123When the kernel is configured with
124.Tn DEBUG
125enabled, the first open to an SES device will spit out overall enclosure
126parameters to the console.
127.Sh HISTORY
128The
129.Nm
130driver was written for the
131.Tn CAM
132.Tn SCSI
133subsystem by Matthew Jacob.
134This is a functional equivalent of a similar
135driver available in Solaris, Release 7.
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: head/share/man/man4/ses.4 70466 2000-12-29 09:18:45Z ru $
27.\"
28.Dd January 29, 2000
29.Dt SES 4
30.Os FreeBSD
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
56SCSI Environmental 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.Aq Pa cam/scsi/scsi_ses.h
81(\fIq.v.\fR).
82.Pp
83.Bl -tag -width SESIOC_GETENCSTAT
84.It Dv SESIOC_GETNOBJ
85Used to find out how many
86.Nm
87objects are driven by this particular device instance.
88.It Dv SESIOC_GETOBJMAP
89Read, from the kernel, an array of SES objects which contains
90the object identifier, which subenclosure it is in, and the
91.Nm
92type of the object.
93.It Dv SESIOC_GETENCSTAT
94Get the overall enclosure status.
95.It Dv SESIOC_SETENCSTAT
96Set the overall enclosure status.
97.It Dv SESIOC_GETOBJSTAT
98Get the status of a particular object.
99.It Dv SESIOC_SETOBJSTAT
100Set the status of a particular object.
101.It Dv SESIOC_GETTEXT
102Get the associated help text for an object (not yet implemented).
103.Nm
104devices often have descriptive text for an object which can tell
105you things like location (e.g, "left power supply").
106.It Dv SESIOC_INIT
107Initialize the enclosure.
108.El
109.Sh EXAMPLE USAGE
110The files contained in
111.Aq Pa usr/share/examples/ses
112show simple mechanisms for how to use these interfaces, as well as a
113very stupid simple monitoring daemon.
114.Sh FILES
115.Bl -tag -width /dev/rsdXXXXX -compact
116.It Pa /dev/ses Ns Ar N
117The
118.Em Nth
119.Nm SES
120device.
121.El
122.Sh DIAGNOSTICS
123When the kernel is configured with
124.Tn DEBUG
125enabled, the first open to an SES device will spit out overall enclosure
126parameters to the console.
127.Sh HISTORY
128The
129.Nm
130driver was written for the
131.Tn CAM
132.Tn SCSI
133subsystem by Matthew Jacob.
134This is a functional equivalent of a similar
135driver available in Solaris, Release 7.