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 "Sep 10, 2013" 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\en", 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