1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH TSALARM 7D "Mar 16, 2004"
   7 .SH NAME
   8 tsalarm \- Alarm device driver
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 tsalarm@0:ctl
  13 .fi
  14 
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The \fBtsalarm\fR driver is a Multi-threaded, loadable non-STREAMS pseudo
  19 driver that manages ALOM alarms. The \fBtsalarm\fR driver provides an interface
  20 through which alarm relays can be controlled on SUNW,Netra-240 and
  21 SUNW,Netra-440 platforms.
  22 .SH HARDWARE INTERFACE
  23 .sp
  24 .LP
  25 The alarm hardware differs depending on platform. The Netra 240 and 440
  26 platforms features four dry contact alarm relays       which are controlled by
  27 ALOM. You can set each alarm to "on" or "off" by  using ioctl interfaces
  28 provided from the host. The four alarms are labeled as "critical," "major,"
  29 "minor," and "user." The user alarm is set by a user application depending on
  30 system condition. LED's in front of the box provide a visual indication of the
  31 four alarms. The number of alarms and their meanings/labels may vary across
  32 platforms.
  33 .SH IOCTLS
  34 .sp
  35 .LP
  36 The interface provided by the \fBtsalarm\fR driver comprises ioctls that enable
  37 applications to manipulate the alarm module. The alarm  module is accessed via
  38 two device nodes:  i) \fB/dev/lom\fR and \fB/dev/tsalarm:ctl\fR.
  39 .sp
  40 .LP
  41 The following ioctls are supported by  the \fB/dev/lom\fR and
  42 \fB/dev/tsalarm:ctl\fR devices:
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fBTSIOCALCTL - Turn an alarm on or off.\fR\fR
  47 .ad
  48 .sp .6
  49 .RS 4n
  50 The argument is a pointer to the \fBts_aldata_t/lom_aldata_t\fR structure. This
  51 structure is described below. \fBalarm_no member\fR is an integer which
  52 specifies the alarm to which the command is to be applied. The
  53 \fBalarm_state/state\fR structure member indicates the state to which the alarm
  54 should be set (where 0 == off). An error  (\fBEINVAL\fR) is returned if either
  55 an invalid alarm_no or invalid alarm_state is provided.
  56 .RE
  57 
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fBTSIOCALSTATE - Get the state of the alarms.\fR\fR
  62 .ad
  63 .sp .6
  64 .RS 4n
  65 The argument is a pointer to the \fBts_aldata_t/lom_aldata_t\fR structure. This
  66 structure is described below. \fBalarm_no member\fR is an integer which
  67 indicates the alarm to which the command will be applied. The
  68 \fBalarm_state\fR member holds the alarm's current state and is filled in by
  69 the driver. A zero indicates that the alarm is off. An error (\fBEINVAL\fR) is
  70 returned if an invalid alarm_no is provided. The structures and definitions for
  71 the  values  are defined below.
  72 .RE
  73 
  74 .sp
  75 .LP
  76 Alarm values:
  77 .sp
  78 .in +2
  79 .nf
  80 The following old style values are defined in <lom.io.h>
  81 
  82      #define ALARM_NUM_0         0 /* number of zero'th alarm */
  83 
  84      #define ALARM_NUM_1         1 /* number of first alarm */
  85 
  86      #define ALARM_NUM_2         2 /* number of second alarm */
  87 
  88      #define ALARM_NUM_3         3 /* number of third alarm */
  89 
  90   Alarm values defined in <lom.io.h>
  91 
  92      #define ALARM_OFF          0 /* Turn off alarm */
  93 
  94      #define ALARM_ON           1 /* Turn on alarm */
  95 .fi
  96 .in -2
  97 
  98 .sp
  99 .LP
 100 Alarm Data Structure:
 101 .sp
 102 .in +2
 103 .nf
 104 This structure is defined in <lom.io.h>
 105 
 106      typedef struct {
 107 
 108           int alarm_no;       /* alarm to apply command to */
 109 
 110           int alarm_state;    /* state of alarm (0 == off) */
 111 
 112      } ts_aldata_t;
 113 .fi
 114 .in -2
 115 
 116 .sp
 117 .LP
 118 Use the following LOM interfaces to get and set the alarms. These definitions
 119 are included in <lom_io.h>
 120 .sp
 121 .in +2
 122 .nf
 123     #define ALARM_CRITICAL         0 /* number of critical alarm */
 124 
 125     #define ALARM_MAJOR            1 /* number of major alarm */
 126 
 127     #define ALARM_MINOR            2 /* number of minor alarm */
 128 
 129     #define ALARM_USER             3 /* number of user alarm */
 130 .fi
 131 .in -2
 132 
 133 .sp
 134 .LP
 135 The following alarm data structure is provided in <lom_io.h>:
 136 .sp
 137 .in +2
 138 .nf
 139 typedef struct {
 140 
 141         int alarm_no;
 142 
 143         int state;
 144 
 145     } lom_aldata_t;
 146 .fi
 147 .in -2
 148 
 149 .SH ERRORS
 150 .sp
 151 .LP
 152 An \fBopen()\fR will fail if:
 153 .sp
 154 .ne 2
 155 .na
 156 \fBENXIO\fR
 157 .ad
 158 .RS 9n
 159 The driver is not installed in the system.
 160 .RE
 161 
 162 .sp
 163 .LP
 164 An \fBioctl()\fR will fail if:
 165 .sp
 166 .ne 2
 167 .na
 168 \fBEFAULT\fR
 169 .ad
 170 .RS 10n
 171 There was a hardware failure during the specified operation.
 172 .RE
 173 
 174 .sp
 175 .ne 2
 176 .na
 177 \fBEINVAL\fR
 178 .ad
 179 .RS 10n
 180 The alarm number specified is not valid or an invalid value was supplied.
 181 .RE
 182 
 183 .sp
 184 .ne 2
 185 .na
 186 \fBENXIO\fR
 187 .ad
 188 .RS 10n
 189 The driver is not installed in the system or the monitor callback routine could
 190 not be scheduled.
 191 .RE
 192 
 193 .SH EXAMPLES
 194 .sp
 195 .in +2
 196 .nf
 197 How to set an alarm:
 198 
 199      #include <sys/unistd.h>
 200      #include <fcntl.h>
 201      #include <stdio.h>
 202      #include <lom_io.h>
 203 
 204      #define LOM_DEVICE "/dev/lom"
 205 
 206      int
 207      main()
 208      {
 209         lom_aldata_t lld;
 210         int fd = open(LOM_DEVICE, O_RDWR);
 211 
 212         if (fd == -1) {
 213                 printf("Error opening device: %s\n", LOM_DEVICE);
 214                 exit (1);
 215         }
 216 
 217         lld.alarm_no = ALARM_CRITICAL;   /* Set the critical alarm */
 218         lld.state = ALARM_ON;   /* Set the alarm */
 219 
 220         if (ioctl(fd, LOMIOCALCTL, (char *)&lld) != 0)
 221                 printf("Setting alarm failed");
 222         else
 223                 printf("Alarm set successfully");
 224 
 225         close(fd);
 226 
 227      }
 228 .fi
 229 .in -2
 230 
 231 .SH FILES
 232 .sp
 233 .ne 2
 234 .na
 235 \fB\fB/dev/lom\fR\fR
 236 .ad
 237 .sp .6
 238 .RS 4n
 239 LOM device.
 240 .RE
 241 
 242 .sp
 243 .ne 2
 244 .na
 245 \fB\fB/dev/tsalarm:ctl\fR\fR
 246 .ad
 247 .sp .6
 248 .RS 4n
 249 Alarm control device.
 250 .RE
 251 
 252 .sp
 253 .ne 2
 254 .na
 255 \fB\fB/platform/platform/kernel/drv/sparcv9/tsalarm\fR\fR
 256 .ad
 257 .sp .6
 258 .RS 4n
 259 Device driver module.
 260 .RE
 261 
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fB/platform/SUNW,Netra-240/kernel/drv/tsalarm.conf\fR\fR
 266 .ad
 267 .sp .6
 268 .RS 4n
 269 Driver configuration file.
 270 .RE
 271 
 272 .SH ATTRIBUTES
 273 .sp
 274 .LP
 275 See \fBattributes\fR(5) for descriptions of the following attributes:
 276 .sp
 277 
 278 .sp
 279 .TS
 280 box;
 281 c | c
 282 l | l .
 283 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 284 _
 285 Architecture    SPARC
 286 .TE
 287 
 288 .SH SEE ALSO
 289 .sp
 290 .LP
 291 \fBattributes\fR(5)
 292 .sp
 293 .LP
 294 \fIWriting Device Drivers\fR