share/man/man4/vkbd.4

   1 .\" $Id: vkbd.4,v 1.4 2004/11/16 16:49:39 max Exp $
   2 .\" $FreeBSD$
   3 .\"
   4 .Dd August 12, 2004
   5 .Dt VKBD 4
   6 .Os
   7 .Sh NAME
   8 .Nm vkbd
   9 .Nd the virtual AT keyboard interface
  10 .Sh SYNOPSIS
  11 .Cd "device vkbd"
  12 .Sh DESCRIPTION
  13 The
  14 .Nm
  15 interface is a software loopback mechanism that can be loosely
  16 described as the virtual AT keyboard analog of the
  17 .Xr pty 4 ,
  18 that is,
  19 .Nm
  20 does for virtual AT keyboards what the
  21 .Xr pty 4
  22 driver does for terminals.
  23 .Pp
  24 The
  25 .Nm
  26 driver, like the
  27 .Xr pty 4
  28 driver, provides two interfaces: a keyboard interface like the usual
  29 facility it is simulating (a virtual AT keyboard in the case of
  30 .Nm ,
  31 or a terminal for
  32 .Xr pty 4 ) ,
  33 and a character-special device
  34 .Dq control
  35 interface.
  36 .Pp
  37 The virtual AT keyboards are named
  38 .Pa vkbd0 , vkbd1 ,
  39 etc., one for each control device that has been opened.
  40 .Pp
  41 The
  42 .Nm
  43 interface permits opens on the special control device
  44 .Pa /dev/vkbdctl .
  45 When this device is opened,
  46 .Nm
  47 will return a handle for the lowest unused
  48 .Pa vkbdctl
  49 device (use
  50 .Xr devname 3
  51 to determine which).
  52 .Pp
  53 Each virtual AT keyboard supports the usual keyboard interface
  54 .Xr ioctl 2 Ns s ,
  55 and thus can be used with
  56 .Xr kbdcontrol 1
  57 like any other keyboard.
  58 The control device supports exactly the same
  59 .Xr ioctl 2 Ns s
  60 as the virtual AT keyboard device.
  61 Writing AT scan codes to the control device generates an input on
  62 the virtual AT keyboard, as if the
  63 (non-existent)
  64 hardware had just received it.
  65 .Pp
  66 The virtual AT keyboard control device, normally
  67 .Pa /dev/vkbdctl Ns Aq Ar N ,
  68 is exclusive-open
  69 (it cannot be opened if it is already open)
  70 and is restricted to the super-user.
  71 A
  72 .Xr read 2
  73 call will return the virtual AT keyboard status structure
  74 (defined in
  75 .In dev/vkbd/vkbd_var.h )
  76 if one is available;
  77 if not, it will either block until one is or return
  78 .Er EWOULDBLOCK ,
  79 depending on whether non-blocking I/O has been enabled.
  80 .Pp
  81 A
  82 .Xr write 2
  83 call passes AT scan codes to be
  84 .Dq received
  85 from the virtual AT keyboard.
  86 Each AT scan code must be passed as
  87 .Vt "unsigned int" .
  88 Although AT scan codes must be passes as
  89 .Vt "unsigned int" Ns s ,
  90 the size of the buffer passed to
  91 .Xr write 2
  92 still should be in bytes, i.e.,
  93 .Bd -literal -offset indent
  94 static unsigned int     codes[] =
  95 {
  96 /*      Make    Break */
  97         0x1e,   0x9e
  98 };
  99
 100 int
 101 main(void)
 102 {
 103         int     fd, len;
 104
 105         fd = open("/dev/vkbdctl0", O_RDWR);
 106         if (fd < 0)
 107                 err(1, "open");
 108
 109         /* Note sizeof(codes) - not 2! */
 110         len = write(fd, codes, sizeof(codes));
 111         if (len < 0)
 112                 err(1, "write");
 113
 114         close(fd);
 115
 116         return (0);
 117 }
 118 .Ed
 119 .Pp
 120 Write will block if there is not enough space in the input queue.
 121 .Pp
 122 The control device also supports
 123 .Xr select 2
 124 for read and write.
 125 .Pp
 126 On the last close of the control device, the virtual AT keyboard is removed.
 127 All queued scan codes are thrown away.
 128 .Sh SEE ALSO
 129 .Xr kbdcontrol 1 ,
 130 .Xr atkbdc 4 ,
 131 .Xr psm 4 ,
 132 .Xr syscons 4
 133 .Sh HISTORY
 134 The
 135 .Nm
 136 module was implemented in
 137 .Fx 6.0 .
 138 .Sh AUTHORS
 139 .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
 140 .Sh CAVEATS
 141 The
 142 .Nm
 143 interface is a software loopback mechanism, and, thus
 144 .Xr ddb 4
 145 will not work with it.
 146 Current implementation of the
 147 .Xr syscons 4
 148 driver can accept input from only one keyboard, even if it is virtual.
 149 Thus it is not possible to have both wired and virtual keyboard to be active
 150 at the same time.
 151 It is, however, in principal possible to obtain AT scan
 152 codes from the different sources and write them into the same virtual keyboard.
 153 The virtual keyboard state synchronization is the user's responsibility.