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