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