share/man/man7d/virtualkm.7d

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