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