VKBD(4)

🌸 VKBD(4) — the virtual AT keyboard interface 🌸

okay so bestie, we're talking about vkbd today, and it's a kernel interfaces manual situation, so buckle up 💅

---

✨ NAME ✨

vkbd — the virtual AT keyboard interface 🎹

---

🦋 SYNOPSIS 🦋

device vkbd

---

💖 DESCRIPTION 💖

okay so the vkbd interface is literally a software loopback mechanism, and the vibe is basically "virtual AT keyboard analog of the pty(4)" — like, vkbd does for virtual AT keyboards what the pty(4) driver does for terminals, no cap 🫶

The vkbd driver, same as pty(4), gives you two interfaces: a keyboard interface like the usual facility it's simulating (a virtual AT keyboard in the vkbd case, or a terminal for pty(4)), plus a character-special device "control" interface. two-for-one, iconic 👑

The virtual AT keyboards are named vkbd0, vkbd1, etc., one for each control device that has been opened. so cute, they're numbered 🌈

The vkbd interface permits opens on the special control device /dev/vkbdctl. When this device is opened, vkbd will return a handle for the lowest unused vkbdctl device (use devname(3) to figure out which one, iykyk).

Each virtual AT keyboard supports the usual keyboard interface ioctl(2)s, so it can be used with kbdcontrol(1) like any other keyboard, fr fr. 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. ghost keyboard behavior, we love to see it 💀

---

🎀 the control device deets 🎀

The virtual AT keyboard control device, normally /dev/vkbdctl⟨N⟩, is exclusive-open — meaning it literally cannot be opened if it's already open, no sharing besties 🙈 — 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'll either block until one is, or return EWOULDBLOCK, depending on whether non-blocking I/O has been enabled. choose your adventure ✨

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. Even though 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);
}

write will block if there's not enough space in the input queue. patience, babe 🧚

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 are thrown away — gone, deleted, into the void 🗑️

---

👑 SEE ALSO 👑

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

---

⭐ HISTORY ⭐

The vkbd module was implemented in FreeBSD 6.0. vintage, we stan a legacy icon 🎀

---

💜 AUTHORS 💜

Maksim Yevmenkin <m_evmenkin@yahoo.com> — thank you king 🫶

---

🔥 CAVEATS 🔥

okay this is the part where you pay attention, bestie 😭

The vkbd interface is a software loopback mechanism, and, thus, ddb(4) will not work with it. nope. not happening 💀

Current implementation of the syscons(4) driver can accept input from only one keyboard, even if it's virtual. So it is not possible to have both a wired and virtual keyboard active at the same time. sad but true 🙈

It is, however, in principal possible to obtain AT scan codes from different sources and write them into the same virtual keyboard. The virtual keyboard state synchronization is the user's responsibility though — that's on you, bestie, no cap 🌸

---

anyway that's the whole page, mwah 💋 — signed off from the Debian edition, dated August 12, 2004, slay 🦋✨