VKBD(4)

VKBD(4) 💖

okay bestie, so this is a page from the Kernel Interfaces Manual, and it's all about vkbd — the virtual AT keyboard interface. yes you read that right, a keyboard that isn't even real. we love a fake-it-till-you-make-it icon ✨

---

✨ NAME ✨

vkbd — the virtual AT keyboard interface 👑

---

✨ SYNOPSIS ✨

device vkbd

that's it. that's the whole summoning ritual. put this in your kernel config and the vibes arrive 🦋

---

✨ DESCRIPTION ✨

So like, the vkbd interface is a software loopback mechanism — which is a fancy way of saying it's the virtual AT keyboard equivalent of pty(4). Fr fr, vkbd does for virtual AT keyboards exactly what the pty(4) driver does for terminals. Same energy, different hardware. 💅

The vkbd driver, just like pty(4), serves up two interfaces: a keyboard interface that mimics the usual facility it's simulating (a virtual AT keyboard for vkbd, or a terminal for pty(4)), and a character-special device “control” interface. Two-for-one, no cap. 🎀

The virtual AT keyboards get named vkbd0, vkbd1, etc. — one for each control device that has been opened. They're like little keyboard babies. 🥺

The vkbd interface lets you open the special control device /dev/vkbdctl. When you open it, vkbd hands back a handle for the lowest unused vkbdctl device — and you can use devname(3) to figure out which one you actually got. Iykyk. 🔍

Each virtual AT keyboard supports the usual keyboard interface ioctl(2)s, so you can use it with kbdcontrol(1) like it's any other keyboard, because why should the fake ones be left out. The control device supports exactly the same ioctl(2)s as the virtual AT keyboard device. Writing AT scan codes to the control device generates an input on the virtual AT keyboard, as if the (non-existent) hardware had just received it. Delulu but make it functional. 😭

The virtual AT keyboard control device, normally /dev/vkbdctl⟨N⟩, is exclusive-open — meaning it absolutely cannot be opened if it's already open, no sharing, no splitting, it's giving possessive girlfriend energy 💀 — and it's restricted to the super-user. A read(2) call will return the virtual AT keyboard status structure (defined in <dev/vkbd/vkbd_var.h>) if one is available; if not, it will either block until one is or return EWOULDBLOCK, depending on whether non-blocking I/O has been enabled. Pick your fighter. 🫶

A write(2) call passes AT scan codes to be “received” from the virtual AT keyboard. Each AT scan code must be passed as unsigned int. And here's the gotcha that gets everybody: although AT scan codes must be passed as unsigned ints, the size of the buffer passed to write(2) still should be in bytes, i.e.:

static unsigned int     codes[] =
{
/*      Make    Break */
        0x1e,   0x9e
};

int
main(void)
{
        int     fd, len;

        fd = open("/dev/vkbdctl0", O_RDWR);
        if (fd < 0)
                err(1, "open");

        /* Note sizeof(codes) - not 2! */
        len = write(fd, codes, sizeof(codes));
        if (len < 0)
                err(1, "write");

        close(fd);

        return (0);
}

⚠️ bestie the /* Note sizeof(codes) - not 2! */ comment is doing the lord's work. use sizeof(codes). do NOT hardcode a 2. that is the trap. 🚨

Write will block if there is not enough space in the input queue. Patience is a virtue etc etc. 🌸

The control device also supports select(2) for read and write. Multitasking queen. ⭐

On the last close of the control device, the virtual AT keyboard is removed. And all queued scan codes? Thrown away. Gone. Deleted. Sent to the void. 🙈

---

✨ SEE ALSO ✨

• kbdcontrol(1)
• atkbdc(4)
• psm(4)
• syscons(4)
• vt(4)

go read the whole friend group, they're all connected 🦋

---

✨ HISTORY ✨

The vkbd module was implemented in FreeBSD 6.0. a classic, an icon, a legend, we stan an OG 💜

---

✨ AUTHORS ✨

Maksim Yevmenkin <m_evmenkin@yahoo.com> — thank you for your service, king 👑

---

✨ CAVEATS ✨

💀 read this part. actually read it. it matters.

The vkbd interface is a software loopback mechanism, and, thus ddb(4) will not work with it. no debugger for you. sad but true.

Current implementation of the syscons(4) driver can accept input from only one keyboard, even if it is virtual. So it is not possible to have both a wired and a virtual keyboard active at the same time. Pick one. There can only be one main character. 👑

It is, however, in principal possible to obtain AT scan codes from the different sources and write them into the same virtual keyboard. But heads up: the virtual keyboard state synchronization is the user's responsibility. That's on you bestie, the kernel is not holding your hand for that one. 🫶

---

and that's the whole page!! 🌈 this manual page came from Debian, dated August 12, 2004 — yes, a vintage. an antique. a collector's item. it was doing virtual keyboards before it was cool. 💅✨🎀

mwah, go write some scan codes responsibly 💖