xref: /illumos-gate/usr/src/uts/common/sys/vuid_event.h (revision 2d6eb4a5)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License, Version 1.0 only
6  * (the "License").  You may not use this file except in compliance
7  * with the License.
8  *
9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10  * or http://www.opensolaris.org/os/licensing.
11  * See the License for the specific language governing permissions
12  * and limitations under the License.
13  *
14  * When distributing Covered Code, include this CDDL HEADER in each
15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16  * If applicable, add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your own identifying
18  * information: Portions Copyright [yyyy] [name of copyright owner]
19  *
20  * CDDL HEADER END
21  */
22 /*
23  * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 #ifndef _SYS_VUID_EVENT_H
28 #define	_SYS_VUID_EVENT_H
29 
30 #include <sys/types.h>
31 #include <sys/types32.h>
32 
33 #ifdef	__cplusplus
34 extern "C" {
35 #endif
36 
37 /*
38  * This file describes a virtual user input device (vuid) interface.  This
39  * is an interface between input devices and their clients.  The interface
40  * defines an idealized user input device that may not correspond to any
41  * existing physical collection of input devices.
42  *
43  * It is targeted to input devices that gather command data from humans,
44  * e.g., mice, keyboards, tablets, joysticks, light pens, knobs, sliders,
45  * buttons, ascii terminals, etc.  The vuid interface is specifically not
46  * designed to support input devices that produce voluminous amounts of
47  * data, e.g., input scanners, disk drives, voice packets.
48  *
49  * Here are some of the properties that are expected of a typical client
50  * of vuid:
51  *
52  *	The client has a richer user interface than can be supported by
53  *	a simple ascii terminal.
54  *
55  *	The client serializes multiple input devices being used
56  *	by the user into a single stream of events.
57  *
58  *	The client preserves the entire state of its input so that
59  *	it may query this state.
60  *
61  * Here are some features that vuid provides to its clients:
62  *
63  *	A client may extend the capabilities of the predefined vuid by
64  *	adding input devices.  A client wants to be able to do this in
65  *	a way that fits smoothly with its existing input paradigm.
66  *
67  *	A client can write its code to be input device independent.  A
68  *	client can replace the underlaying physical devices and not
69  *	have to be concerned.  In fact, the vuid interface doesn't
70  *	really care about physical devices.  One physical device can
71  *	masquerade a many logical devices and many physical devices can
72  *	look like a single logical device.
73  *
74  * This file defines the protocol that makes up the virtual user input
75  * device.  This includes:
76  *
77  *	The vuid station codes and there meanings.
78  *
79  *	The form by which changes to vuid stations, i.e., firm events,
80  *	are communicated to clients (typically via the read system
81  *	call).
82  *
83  *	The form by which clients send commands to input devices that
84  *	support the vuid (typically via an ioctl system call to send
85  *	vuid instead of a native byte stream).
86  *
87  * Explicitly, this file does not define:
88  *
89  *	How to store the state of the vuid
90  *	(see ../sunwindowdev/vuid_state.h).
91  *
92  *	How to dynamically allocate additional vuid segments in order
93  *	to extend the vuid (one could statically allocate additional
94  *	vuid segments by treating this file as the central registry
95  *	of vuid segments).
96  */
97 
98 /*
99  * VUID_SEG_SIZE is the size of a virtual user input "device" address space
100  * segment.
101  */
102 #define	VUID_SEG_SIZE	(256)
103 
104 /*
105  * This is the central registry of virtual user input devices.
106  * To allocate a new vuid:
107  *
108  *	o Choose an unused portion of the address space.
109  *	  Vuids from 0x00 to 0x7F are reserved for Sun implementers.
110  *	  Vuids from 0x80 to 0xFF are reserved for Sun customers.
111  *
112  *	o Note the new device with a *_DEVID define.  Breifly describe
113  *	  the purpose/usage of the device.  Point to the place where
114  *	  more information can be found.
115  *
116  *	o Note the new device with a VUID_* entry in the Vuid_device
117  *	  enumeration.
118  *
119  *	o List the specific event codes in another header file that is
120  *	  specific to the new device (ASCII_DEVID, TOP_DEVID &
121  *	  WORKSTATION_DEVID events are listing here for historical
122  *	  reasons).
123  */
124 
125 #define	ASCII_DEVID		0x00
126 	/* Ascii codes, which include META codes and 8-bit EUC codes */
127 	/* (see below) */
128 #define	TOP_DEVID		0x01
129 	/* Top codes, which is ASCII with the 9th bit on (see below) */
130 #define	ISO_DEVID		0x02
131 	/* ISO characters 0x80 - 0xFF (backwards compatibility) */
132 /* ... Sun implementers add new device ids here ... */
133 #define	WHEEL_DEVID		0x78
134 #define	LIGHTPEN_DEVID		0x79
135 	/* Lightpen events for	Lightpen */
136 #define	BUTTON_DEVID		0x7A
137 	/* Button events from Sun button box */
138 #define	DIAL_DEVID		0x7B
139 	/* Dial events from Sun dial box */
140 #define	SUNVIEW_DEVID		0x7C
141 	/* Sunview Semantic events */
142 #define	PANEL_DEVID		0x7D
143 	/* Panel subwindow package event codes passed around internal */
144 	/* to the panel package (see <suntool/panel.h>) */
145 #define	SCROLL_DEVID		0x7E
146 	/* Scrollbar package event codes passed to scrollbar clients on */
147 	/* interesting scrollbar activity (see <suntool/scrollbar.h>) */
148 #define	WORKSTATION_DEVID	0x7F
149 	/* Virtual keyboard and locator (mouse) related event codes */
150 	/* that describe a basic "workstation" device collection (see below). */
151 	/* This device is a bit of a hodge podge for historical reasons; */
152 	/* the middle of the address space has SunWindows related events */
153 	/* in it (see <sunwindow/win_input.h >), and the virtual keyboard */
154 	/* and virtual locator are thrown together. */
155 /* ... Sun customers add new device ids here ... */
156 #define	LAST_DEVID		0xFF
157 	/* No more device ids beyond LAST_DEVID */
158 
159 typedef enum vuid_device {
160 	VUID_ASCII = ASCII_DEVID,
161 	VUID_TOP = TOP_DEVID,
162 	VUID_ISO = ISO_DEVID,
163 	VUID_WHEEL = WHEEL_DEVID,
164 	VUID_LIGHTPEN = LIGHTPEN_DEVID,
165 	VUID_DIAL = DIAL_DEVID,
166 	VUID_SUNVIEW = SUNVIEW_DEVID,
167 	VUID_PANEL = PANEL_DEVID,
168 	VUID_SCROLL = SCROLL_DEVID,
169 	VUID_WORKSTATION = WORKSTATION_DEVID,
170 	VUID_LAST = LAST_DEVID
171 } Vuid_device;
172 
173 #define	vuid_first(devid)	((devid) << 8)
174 #define	vuid_last(devid)	(((devid) << 8)+VUID_SEG_SIZE-1)
175 #define	vuid_in_range(devid, id) \
176 	    ((id >= vuid_first(devid)) && (id <= vuid_last(devid)))
177 
178 /*
179  * EUC (Extended UNIX Code) device related definitions:
180  */
181 #define	EUC_FIRST	(0)
182 #define	EUC_LAST	(255)
183 
184 /*
185  * Old ASCII definitions for backwards compatibility:
186  */
187 #define	ASCII_FIRST	(0)
188 #define	ASCII_LAST	(127)
189 #define	META_FIRST	(128)
190 #define	META_LAST	(255)
191 
192 /*
193  * Top device related definitions:
194  */
195 #define	TOP_FIRST	(256)
196 #define	TOP_LAST	(511)
197 
198 /*
199  * Old ISO definitions for backwards compatibility:
200  */
201 #define	ISO_FIRST	(512)
202 #define	ISO_LAST	(767)
203 
204 /*
205  * Workstation device related definitions.  First are virtual keyboard
206  * assignments.	 All events for the virtual keyboard have 0 (went up) or
207  * 1 (went down) values.
208  */
209 
210 #define	VKEY_FIRST	vuid_first(WORKSTATION_DEVID)
211 #define	VKEY_UP		0
212 #define	VKEY_DOWN	1
213 
214 #define	VKEY_KBD_CODES	(128)	/* The number of event codes in a subset of */
215 				/* the workstation device's address space */
216 				/* that belong to the virtual keyboard */
217 
218 #define	VKEY_FIRSTPSEUDO	(VKEY_FIRST)			/* 32512 */
219 /*
220  * VKEY_FIRSTPSEUDO thru VKEY_LASTPSEUDO are taken (for historical
221  * reasons) by SunWindows related codes (see <sunwindow/win_input.h >).
222  */
223 #define	VKEY_LASTPSEUDO		(VKEY_FIRSTPSEUDO+15)		/* 32527 */
224 
225 #define	VKEY_FIRSTSHIFT		(VKEY_LASTPSEUDO+1)		/* 32528 */
226 #define	SHIFT_CAPSLOCK		(VKEY_FIRSTSHIFT+0)		/* 32528 */
227 #define	SHIFT_LOCK		(VKEY_FIRSTSHIFT+1)		/* 32529 */
228 #define	SHIFT_LEFT		(VKEY_FIRSTSHIFT+2)		/* 32530 */
229 #define	SHIFT_RIGHT		(VKEY_FIRSTSHIFT+3)		/* 32531 */
230 #define	SHIFT_LEFTCTRL		(VKEY_FIRSTSHIFT+4)		/* 32532 */
231 /* SHIFT_CTRL is for compatability with previous releases */	/* 32532 */
232 #define	SHIFT_CTRL		SHIFT_LEFTCTRL			/* 32532 */
233 #define	SHIFT_RIGHTCTRL		(VKEY_FIRSTSHIFT+5)		/* 32533 */
234 #define	SHIFT_META		(VKEY_FIRSTSHIFT+6)		/* 32534 */
235 #define	SHIFT_TOP		(VKEY_FIRSTSHIFT+7)		/* 32535 */
236 #define	SHIFT_CMD		(VKEY_FIRSTSHIFT+8)		/* 32536 */
237 #define	SHIFT_ALTG		(VKEY_FIRSTSHIFT+9)		/* 32537 */
238 #define	SHIFT_ALT		(VKEY_FIRSTSHIFT+10)		/* 32538 */
239 #define	SHIFT_NUMLOCK		(VKEY_FIRSTSHIFT+11)		/* 32539 */
240 #define	VKEY_LASTSHIFT		(VKEY_FIRSTSHIFT+15)		/* 32543 */
241 
242 #define	VKEY_FIRSTFUNC		(VKEY_LASTSHIFT+1)		/* 32544 */
243 
244 #define	BUT_FIRST		(VKEY_FIRSTFUNC)		/* 32544 */
245 #define	BUT(i)			((BUT_FIRST)+(i)-1)		/* 32544+i-1 */
246 #define	BUT_LAST		(BUT_FIRST+9)			/* 32553 */
247 
248 #define	KEY_LEFTFIRST		((BUT_LAST)+1)			/* 32554 */
249 #define	KEY_LEFT(i)		((KEY_LEFTFIRST)+(i)-1)		/* 32554+i-1 */
250 #define	KEY_LEFTLAST		((KEY_LEFTFIRST)+15)		/* 32569 */
251 
252 #define	KEY_RIGHTFIRST		((KEY_LEFTLAST)+1)		/* 32570 */
253 #define	KEY_RIGHT(i)		((KEY_RIGHTFIRST)+(i)-1)	/* 32570+i-1 */
254 #define	KEY_RIGHTLAST		((KEY_RIGHTFIRST)+15)		/* 32585 */
255 
256 #define	KEY_TOPFIRST		((KEY_RIGHTLAST)+1)		/* 32586 */
257 #define	KEY_TOP(i)		((KEY_TOPFIRST)+(i)-1)		/* 32586+i-1 */
258 #define	KEY_TOPLAST		((KEY_TOPFIRST)+15)		/* 32601 */
259 
260 #define	KEY_BOTTOMLEFT		((KEY_TOPLAST)+1)		/* 32602 */
261 #define	KEY_BOTTOMRIGHT		((KEY_BOTTOMLEFT)+1)		/* 32603 */
262 #define	KEY_BOTTOMFIRST		((KEY_TOPLAST)+1)		/* 32602 */
263 #define	KEY_BOTTOM(i)		((KEY_BOTTOMFIRST)+(i)-1)	/* 32602+i-1 */
264 #define	KEY_BOTTOMLAST		((KEY_BOTTOMFIRST)+15)		/* 32617 */
265 
266 #define	VKEY_LASTFUNC		(VKEY_FIRSTFUNC+73)		/* 32617 */
267 
268 #define	VKEY_FIRSTPAD		(VKEY_LASTFUNC+1)		/* 32618 */
269 
270 #define	VKEY_PADEQUAL		(VKEY_FIRSTPAD+0)		/* 32618 */
271 #define	VKEY_PADSLASH		(VKEY_FIRSTPAD+1)		/* 32619 */
272 #define	VKEY_PADSTAR		(VKEY_FIRSTPAD+2)		/* 32620 */
273 #define	VKEY_PADMINUS		(VKEY_FIRSTPAD+3)		/* 32621 */
274 #define	VKEY_PADSEP		(VKEY_FIRSTPAD+4)		/* 32622 */
275 #define	VKEY_PAD7		(VKEY_FIRSTPAD+5)		/* 32623 */
276 #define	VKEY_PAD8		(VKEY_FIRSTPAD+6)		/* 32624 */
277 #define	VKEY_PAD9		(VKEY_FIRSTPAD+7)		/* 32625 */
278 #define	VKEY_PADPLUS		(VKEY_FIRSTPAD+8)		/* 32626 */
279 #define	VKEY_PAD4		(VKEY_FIRSTPAD+9)		/* 32627 */
280 #define	VKEY_PAD5		(VKEY_FIRSTPAD+10)		/* 32628 */
281 #define	VKEY_PAD6		(VKEY_FIRSTPAD+11)		/* 32629 */
282 #define	VKEY_PAD1		(VKEY_FIRSTPAD+12)		/* 32630 */
283 #define	VKEY_PAD2		(VKEY_FIRSTPAD+13)		/* 32631 */
284 #define	VKEY_PAD3		(VKEY_FIRSTPAD+14)		/* 32632 */
285 #define	VKEY_PAD0		(VKEY_FIRSTPAD+15)		/* 32633 */
286 #define	VKEY_PADDOT		(VKEY_FIRSTPAD+16)		/* 32634 */
287 #define	VKEY_PADENTER		(VKEY_FIRSTPAD+17)		/* 32635 */
288 
289 #define	VKEY_LASTPAD		(VKEY_FIRSTPAD+17)		/* 32635 */
290 
291 #define	VKEY_LAST		(VKEY_FIRST+VKEY_KBD_CODES-1)	/* 32639 */
292 
293 /*
294  * More workstation device definitions.	 These are virtual locator
295  * related event code assignments.  Values for these events are int.
296  * VLOC_BATCH's value is a uint_t that describes the number of events
297  * that follow that should be treated as a batch.
298  */
299 #define	MOUSE_DEVID	WORKSTATION_DEVID	/* Backward compatibility */
300 
301 #define	VLOC_FIRST		(VKEY_LAST+1)			/* 32640 */
302 #define	LOC_FIRST_DELTA		(VLOC_FIRST+0)			/* 32640 */
303 #define	LOC_X_DELTA		(VLOC_FIRST+0)			/* 32640 */
304 #define	LOC_Y_DELTA		(VLOC_FIRST+1)			/* 32641 */
305 #define	LOC_LAST_DELTA		(VLOC_FIRST+1)			/* 32641 */
306 
307 #define	LOC_FIRST_ABSOLUTE	(VLOC_FIRST+2)			/* 32642 */
308 #define	LOC_X_ABSOLUTE		(VLOC_FIRST+2)			/* 32642 */
309 #define	LOC_Y_ABSOLUTE		(VLOC_FIRST+3)			/* 32643 */
310 #define	LOC_LAST_ABSOLUTE	(VLOC_FIRST+3)			/* 32643 */
311 
312 #define	VLOC_BATCH		(VLOC_FIRST+4)			/* 32644 */
313 #define	VLOC_LAST		(VLOC_BATCH+1)			/* 32645 */
314 
315 #define	MOUSE_CAP_CHANGE_FIRST		(VLOC_LAST+1)		/* 32646 */
316 #define	MOUSE_CAP_CHANGE_NUM_BUT	(MOUSE_CAP_CHANGE_FIRST+0) /* 32646 */
317 #define	MOUSE_CAP_CHANGE_NUM_WHEEL	(MOUSE_CAP_CHANGE_FIRST+1) /* 32647 */
318 
319 #define	MOUSE_TYPE_ABSOLUTE	(VLOC_LAST+3)			/* 32648 */
320 
321 #define	MOUSE_LAST		(VLOC_LAST+3)			/* 32648 */
322 #define	KEYBOARD_LAYOUT_CHANGE	(MOUSE_LAST+1)			/* 32649 */
323 
324 /*
325  * Common names for certain input codes.  The buttons on the physical
326  * mouse are thought to actually belong to the virtual keyboard.
327  */
328 #define	MS_LEFT		BUT(1)					/* 32544 */
329 #define	MS_MIDDLE	BUT(2)					/* 32545 */
330 #define	MS_RIGHT	BUT(3)					/* 32546 */
331 
332 /*
333  * A firm_event structure is encoded in the byte stream of a device
334  * when the device has been asked to format its byte stream so.
335  * The time stamp is not defined to be meaningful except to compare
336  * with other Firm_event time stamps.
337  *
338  * The pair field is critical for a state maintainence package
339  * (such as vuid_state.h), one that is designed to not know anything
340  * about the semantics of particular events, to maintain correct data
341  * for corresponding absolute, delta and paired state variables.
342  *
343  * pair, when defined (as indicated by pair_type), is the associated
344  * state variable that should be updated due to this events generation.
345  * This is used to maintain a correspondence between an event that is a
346  * delta and a state that is an absolute value (with a known delta event
347  * defined) and visa versa, e.g., LOC_X_DELTA & LOC_X_ABSOLUTE.
348  * pair is also used to indicate another state variable that
349  * should be updated with the occurrence of this event, e.g., if id is
350  * '^G' then pair could be 'g' or 'G' depending on the state of the shift
351  * key.
352  */
353 typedef struct firm_event {
354 	ushort_t	id;	/* Event's unique id */
355 	uchar_t		pair_type;	/* Event pair's type */
356 #define	FE_PAIR_NONE		0	/* pair is not defined */
357 #define	FE_PAIR_SET		1	/* pair is accompanying id to set */
358 					/* to this events value */
359 #define	FE_PAIR_DELTA		2	/* pair is accompanying id that */
360 					/* should be set to the delta of */
361 					/* id's current value and the new */
362 					/* value indicated by this event */
363 #define	FE_PAIR_ABSOLUTE	3	/* pair is accompanying id that */
364 					/* should be set to the sum of its */
365 					/* current value and the delta */
366 					/* indicated by this event's value */
367 	uchar_t		pair;	/* Event id's associated delta|absolute|pair */
368 				/* offset within id's segment (minus id's */
369 				/* address) */
370 	int		value;	/* Event's value */
371 #if defined(_LP64) || defined(_I32LPx)
372 	struct timeval32 time;	/* Event's time stamp */
373 #else
374 	struct timeval time;
375 #endif
376 } Firm_event;
377 #define	FIRM_EVENT_NULL ((Firm_event *)0)
378 #define	vuid_id_addr(id)		((id) & 0xFF00)
379 #define	vuid_id_offset(id)		((id) & 0xFF)
380 #define	vuid_boolean_value(value)	(((value) == 0) || ((value) == 1))
381 #define	vuid_int_value(value)		(!(vuid_boolean_value((value))))
382 
383 /*
384  * Ioctls to input devices that support vuid.
385  */
386 
387 /*
388  * VUID*FORMAT ioctls are used to control which byte stream format that
389  * a input device should use.  An errno of ENOTTY or EINVAL indicates that
390  * a device can't speak Firm_events.
391  */
392 #define	VUIOC		('v'<<8)
393 #if defined(__i386) || defined(__i386_COMPAT)
394 #define	VUIDSFORMAT   (VUIOC|11) /* avoid conflict with VT_?????? */
395 #define	VUIDGFORMAT   (VUIOC|12) /* avoid conflict with VT_?????? */
396 #else
397 #define	VUIDSFORMAT   (VUIOC|1) /* Set input device byte stream format */
398 #define	VUIDGFORMAT   (VUIOC|2) /* Get input device byte stream format */
399 #endif
400 #define	VUID_NATIVE	0	/* Native byte stream format */
401 #define	VUID_FIRM_EVENT 1	/* struct firm_event byte stream format */
402 
403 /*
404  * VUID*ADDR ioctls are used to control which address a particular
405  * virtual input device segment has.  This is used to have an instancing
406  * capability, e.g., a second mouse.  An errno of ENOTTY indicates that
407  * a device can't deal with these commands.  An errno of ENODEV indicates
408  * that the requested virtual device has no events generated for it by
409  * this physical device.
410  *
411  * VUIDSADDR sets the virtual input device segment address indicated by
412  * default to next.
413  *
414  * VUIDGADDR gets the in force address of the virtual input device segment
415  * indicated by default into current.
416  */
417 typedef struct	vuid_addr_probe {
418 	short	base;		/* default vuid device addr directed too */
419 	union	{
420 		short	next;	/* next addr for default when VUIDSADDR */
421 		short	current; /* current addr of default when VUIDGADDR */
422 	} data;
423 } Vuid_addr_probe;
424 
425 #if defined(__i386) || defined(__i386_COMPAT)
426 #define	VUIDSADDR   (VUIOC|13)	/* avoid conflict with VT_?????? */
427 #define	VUIDGADDR   (VUIOC|14)	/* avoid conflict with VT_?????? */
428 #else
429 #define	VUIDSADDR   (VUIOC|3)	/* Set vuid address */
430 #define	VUIDGADDR   (VUIOC|4)	/* Get vuid address */
431 #endif
432 
433 #ifdef	__cplusplus
434 }
435 #endif
436 
437 #endif	/* _SYS_VUID_EVENT_H */
438