HKBD(4)

🎹 hkbd(4) — the HID keyboard driver, explained 💅

okay so this is a page from the Kernel Interfaces Manual and it's all about hkbd, the HID keyboard driver. if you've ever plugged in a keyboard and thought "girl, why is the console not listening to you", this is your page. let's get into it 🫶

---

✨ NAME ✨

hkbd — the HID keyboard driver. that's it, that's the name, she's simple and she knows what she is 💖

---

🌸 SYNOPSIS 🌸

so to compile this driver into the kernel, you drop the following lines into your kernel configuration file:

device hkbd
device hid
device hidbus
device evdev
options EVDEV_SUPPORT

or, if you're more of a "load it as a module at boot time" kinda bestie, you put this line in loader.conf(5):

hkbd_load="YES"

both valid, both iconic, pick your fighter ✨

---

🦋 DESCRIPTION 🦋

The hkbd driver provides support for keyboards that attach to the HID transport backend. that's the whole gig.

but — and this is the important part — hid(4), hidbus(4), and one of iichid(4) or usbhid(4) must be configured in the kernel as well. no cap, you can't just show up with hkbd alone, she needs her friends 😭

---

🎀 CONFIGURATION 🎀

okay so by default the keyboard subsystem does not create the appropriate devices yet. which is giving "why is nothing working" energy, so make sure you reconfigure your kernel with the following option in the kernel config file:

options KBD_INSTALL_CDEV

now. here's a situation. if both an AT keyboard HID keyboards are used at the same time, the AT keyboard will appear as kbd0 in /dev. The HID keyboards will be kbd1, kbd2, etc. you can see some information about the keyboard with this command:

kbdcontrol -i < /dev/kbd1

or load a keymap with:

kbdcontrol -l keymaps/pt.iso < /dev/kbd1

see kbdcontrol(1) for more possible options — she's got range 👑

you can swap console keyboards by using the command:

kbdcontrol -k /dev/kbd1

from this point on, the first HID keyboard will be the keyboard to be used by the console. main character keyboard, honestly 💅

---

🧚 if you want the HID keyboard as your default 🧚

if you want to use a HID keyboard as your default and not use an AT keyboard at all, you will have to remove the device atkbd line from the kernel configuration file. lowkey annoying but here's why: because of the device initialization order, the HID keyboard will be detected after the console driver initializes itself, and you have to explicitly tell the console driver to use the existence of the HID keyboard. you can do this in one of the following two ways 🫶

way one: run the following command as a part of system initialization:

kbdcontrol -k /dev/kbd0 < /dev/ttyv0 > /dev/null

(Note that as the HID keyboard is the only keyboard, it is accessed as /dev/kbd0)

way two: otherwise tell the console driver to periodically look for a keyboard by setting a flag in the kernel configuration file:

device sc0 at isa? flags 0x100

with the above flag, the console driver will try to detect any keyboard in the system if it did not detect one while it was initialized at boot time. problem solved, slay 🔥

---

🔧 DRIVER CONFIGURATION 🔧

options KBD_INSTALL_CDEV

make the keyboards available through a character device in /dev. that's the vibe 💖

---

options HKBD_DFLT_KEYMAP
makeoptions HKBD_DFLT_KEYMAP=fr.iso

the above lines will put the French ISO keymap in the ukbd driver. (yes, the page says ukbd — that's literally what it says, don't come for me 🙈) you can specify any keymap in /usr/share/syscons/keymaps or /usr/share/vt/keymaps (depending on the console driver being used) with this option. go wild, pick your fave 🌈

---

options KBD_DISABLE_KEYMAP_LOADING

do not allow the user to change the keymap. locked down, no edits, periodt. note that these options also affect the AT keyboard driver, atkbd(4). so like, it's not just a hkbd thing, it's a whole family situation 👑

---

💜 SYSCTL VARIABLES 💜

the following variables are available as both sysctl(8) variables and loader(8) tunables:

• hw.hid.hkbd.debug — Debug output level, where 0 is debugging disabled and larger values increase debug message verbosity. Default is 0. so if you're debugging, crank that number up; if you're just living your life, leave her at zero ✨

---

🍓 FILES 🍓

• /dev/kbd* — blocking device nodes
• /dev/input/event* — input event device nodes.

---

⭐ EXAMPLES ⭐

device hkbd

Add the hkbd driver to the kernel. boom. that's the whole example. short and effective, we love a minimal queen 🎀

---

👑 SEE ALSO 👑

kbdcontrol(1), hid(4), hidbus(4), iichid(4), syscons(4), usbhid(4), vt(4), config(8)

go read those too, iykyk 🦋

---

🌸 AUTHORS 🌸

The hkbd driver was written by Lennart Augustsson <augustss@cs.chalmers.se> for NetBSD and was substantially rewritten for FreeBSD by Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>.

This manual page was written by Nick Hibma <n_hibma@FreeBSD.org> with a large amount of input from Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>.

legends, all of them, we stan 💖💅

---

and that's the page bestie!! this one's from Debian, dated September 12, 2020 — a little vintage, a lot iconic. go forth and keyboard responsibly 🫶✨🎀