| blob | ef96e8e9e29aaf4f98b77752e9baaeed4b8f62c0 |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems All Rights Reserved
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 VIRTUALKM 7D "May 13, 2017"
7 .SH NAME
8 virtualkm \- Virtual keyboard and mouse
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/dev/kbd\fR
13 .fi
15 .LP
16 .nf
17 \fB/dev/mouse\fR
18 .fi
20 .LP
21 .nf
22 \fB#include <sys/types.h>\fR
23 .fi
25 .LP
26 .nf
27 \fB#include <sys/kbio.h>\fR
28 .fi
30 .LP
31 .nf
32 \fBint ioctl(int fildes, int command, ... /*arg*/);\fR
33 .fi
35 .SH DESCRIPTION
36 .LP
37 A virtual keyboard or mouse is an abstraction of one or more physical keyboards
38 or mice (USB or PS2) connected to a system. Input streams for these physical
39 devices are coalesced into a single input stream and appear as a single device
40 to the upper layers.
41 .sp
42 .LP
43 \fB/dev/kbd\fR is the virtual keyboard device file. Inputs from multiple
44 keyboards are coalesced into a single input stream, meaning that all keyboards
45 appear as a single keyboard to a console or window system and accordingly, are
46 treated as a single device. The virtual keyboard layout is consistent with the
47 layout of the first keyboard plugged into the system. Note that on x86
48 platforms, the virtual keyboard layout can be overloaded by \fBeeprom\fR(8).
49 .sp
50 .LP
51 \fB/dev/mouse\fR is the virtual mouse device file. Inputs from multiple mice
52 are coalesced into a single input stream, meaning that all mice appear as
53 single mouse to the window system.
54 .sp
55 .LP
56 Commands from applications are dispatched by the virtual keyboard/mouse
57 facility to the underlying physical devices and will succeed provided that one
58 of the underlying devices responds with success. For example, a single command
59 issued to turn on LED's will turn on corresponding LED's for all underlying
60 physical keyboards.
61 .sp
62 .LP
63 Although physical keyboards/mice are linked to the virtual keyboard/mouse
64 facility, each may be opened separately by accessing its associated device
65 file. (For example, \fB/dev/usb/hid0\fR for a usb mouse). Directly accessing a
66 device file can be useful for multi-seat or similar purposes.
67 .sp
68 .LP
69 When a single physical device is opened via its associated device file, it is
70 automatically removed from the single virtual input stream. When closed, it is
71 automatically re- coalesced into the single virtual input stream.
72 .sp
73 .LP
74 Under the \fBvirtualkm\fR facility, the PS/2 mouse is coalesced into a virtual
75 mouse single input stream and can be accessed using the \fB/dev/mouse\fR file.
76 (Note that in previous releases, the PS/2 mouse was accessed via the
77 \fB/dev/kdmouse\fR physical device file). In the current release, you use the
78 \fB/dev/kdmouse\fR file to directly access the physical PS/2 mouse.
79 .SS "INTERFACES"
80 .LP
81 The virtual mouse provides the following event ID's for mouse capability
82 changes:
83 .sp
84 .ne 2
85 .na
86 \fBMOUSE_CAP_CHANGE_NUM_BUT\fR
87 .ad
88 .RS 30n
89 This event is reported when the total number of mouse buttons changes. The
90 \fBFirm_event.value\fR is set to the new button total, which is the maximum
91 number of all mice buttons. Other fields are ignored.
92 .RE
94 .sp
95 .ne 2
96 .na
97 \fBMOUSE_CAP_CHANGE_NUM_WHEEL\fR
98 .ad
99 .RS 30n
100 This event is reported when the total number of mouse wheels changes. The
101 \fBFirm_event.value\fR is set to the new wheel total. Other fields are ignored.
102 The event value (\fBFirm_event.value\fR) can be 0 (no wheel), 1 (vertical
103 wheel), or 2 (vertical and horizontal wheel).
104 .RE
106 .sp
107 .LP
108 The \fBFirm_event\fR structure is described in <\fBsys/vuid_event.h\fR>. As
109 with other events, firm events are received using \fBread\fR(2).
110 .sp
111 .LP
112 Event ID's are used by applications (including certain mouse demo applications)
113 that are programmed to graphically represent the actual number of buttons and
114 wheels on a mouse. When an application of this type receives a \fBFirm_event\fR
115 with a ID MOUSE_CAP_CHANGE_NUM_BUT or MOUSE_CAP_CHANGE_NUM_WHEEL event, it is
116 instructed to update its state information using the new value. Consider, for
117 example, a mouse demo application whose sole function is to display a mouse
118 with buttons that graphically correspond to the actual number of buttons on the
119 mouse. If, for example, the system has a single two-button USB mouse attached,
120 the application, by default, will graphically display the mouse with a left and
121 a right button. However, if a another three-button USB mouse is hot-plugged
122 into the system, a MOUSE_CAP_CHANGE_NUM_BUT Firm event with
123 \fBFirm_event.value\fR of three instructs the demo application to update the
124 mouse display to indicate three buttons.
125 .SH IOCTLS
126 .ne 2
127 .na
128 \fBKIOCSETFREQ\fR
129 .ad
130 .RS 15n
131 Sets the frequency for either keyboard beeper or console beeper. To set the
132 corresponding beeper frequency, \fIarg\fR must point to a \fBfreq_request\fR
133 structure:
134 .sp
135 .in +2
136 .nf
137 struct freq_request {
138 enum fr_beep_type type; /* beep type */
139 int16_t freq; /* frequency */
140 };
141 .fi
142 .in -2
144 Where \fItype\fR is the corresponding beeper type defined as:
145 .sp
146 .in +2
147 .nf
148 enum fr_beep_type { CONSOLE_BEEP =1, KBD_BEEP =2 };
149 .fi
150 .in -2
152 and \fIfreq\fR is the frequency value to be set as the beeper frequency
153 indicated by \fItype\fR. This value should be between 0 and 32767 with border
154 inclusive.
155 .RE
157 .SH FILES
158 .ne 2
159 .na
160 \fB\fB/dev/kbd\fR\fR
161 .ad
162 .RS 18n
163 Virtual Keyboard device file.
164 .RE
166 .sp
167 .ne 2
168 .na
169 \fB\fB/dev/mouse\fR\fR
170 .ad
171 .RS 18n
172 Virtual Mouse device file.
173 .RE
175 .sp
176 .ne 2
177 .na
178 \fB\fB/dev/kdmouse\fR\fR
179 .ad
180 .RS 18n
181 Physical PS/2 mouse device file.
182 .RE
184 .sp
185 .ne 2
186 .na
187 \fB\fB/dev/usb/hid*\fR\fR
188 .ad
189 .RS 18n
190 Physical USB keyboard/mouse device file.
191 .RE
193 .sp
194 .ne 2
195 .na
196 \fB\fB/etc/dacf.conf\fR\fR
197 .ad
198 .RS 18n
199 Device auto-configuration file.
200 .RE
202 .SH ATTRIBUTES
203 .LP
204 See \fBattributes\fR(5) for descriptions of the following attributes:
205 .sp
207 .sp
208 .TS
209 box;
210 l l
211 l l .
212 ATTRIBUTE TYPE ATTRIBUTE VALUE
213 Architecture SPARC, x86
214 Interface Stability Evolving
215 .TE
217 .SH SEE ALSO
218 .LP
219 \fBkbd\fR(1), \fBeeprom\fR(8), \fBread\fR(2), \fBattributes\fR(5),
220 \fBhid\fR(7D), \fBusba\fR(7D), \fBkb\fR(7M), \fBusbkbm\fR(7M), \fBusbms\fR(7M),
221 \fBvuidmice\fR(7M)
222 .SH DIAGNOSTICS
223 .LP
224 The messages described below may appear on the system console as well as
225 being logged. All messages are formatted in the following manner:
226 .sp
227 .in +2
228 .nf
229 WARNING: Error message...
230 .fi
231 .in -2
232 .sp
234 .sp
235 .ne 2
236 .na
237 \fBconskbd: keyboard is not available for system debugging:
238 \fIdevice_path\fR.\fR
239 .ad
240 .sp .6
241 .RS 4n
242 Errors were encountered while entering kmdb during initialization for debugger
243 mode. As a result, the keyboard is not available.
244 .RE
246 .sp
247 .ne 2
248 .na
249 \fBconskbd: keyboard is not available: <\fIdevice_path\fR>\fR
250 .ad
251 .sp .6
252 .RS 4n
253 Errors were encountered while exiting kmdb during un-initialization for
254 debugger mode. As a result, the keyboard is not available.
255 .RE
257 .sp
258 .ne 2
259 .na
260 \fBFailed to relink the mouse <\fR\fIdevice_path\fR\fB> underneath virtual mouse\fR
261 .ad
262 .sp .6
263 .RS 4n
264 An error was encountered and the mouse is unavailable. (When a mouse is
265 physically opened via a physical device file such as \fB/dev/usb/hid0\fR, it is
266 removed from the single virtual input stream (\fB/dev/mouse\fR). When closed,
267 it is re-coalesced into a single virtual input stream beneath \fB/dev/mouse\fR.
268 If an error is encountered, (for example, the mouse has been physically
269 removed), it is unavailable beneath \fB/dev/mouse\fR.
270 .RE
272 .SH NOTES
273 .LP
274 Currently, the \fBvirtualkm\fR device supports only USB and PS2 keyboards and
275 mice.
276 .sp
277 .LP
278 The \fBvirtualkm\fR device maintains complete compatibility on select legacy
279 systems, (including Ultra 10's), that are equipped with serial keyboard/mouse.