Subject: Newer multimedia keyboards and NetBSD
To: None <>
From: Martijn van Buul <>
List: current-users
Date: 02/03/2007 00:40:19

I posted something like this in netbsd-help@ a while ago, asking about
how to make NetBSD play nice with these keyboards, but didn't get any 
response there, probably because my initial question ("How do I make these
work") can only be answered with "You can't, really".

So, I'm now trying to figure out what needs to be done to make these work. 
In a nutshell, the problem is this:

Some newer keyboards no longer generate "normal" PS/2 scancodes for 
multimedia (or extended) keys. Instead, these keys are mapped to a second
USB HID device. My own Microsoft Natural keyboard does this, and I'm told
that some Logitech ones behave the same. They're actually composite devices,
with one configuration binding to ukbd, and the rest to the generic
uhid driver:

uhidev0 at uhub3 port 3 configuration 1 interface 0
uhidev0: Microsoft NaturalM-BM-. Ergonomic Keyboard 4000, rev 2.00/1.73, addr 4, iclass 3/1
ukbd0 at uhidev0
wskbd1 at ukbd0 mux 1
wskbd1: connecting to wsdisplay0
uhidev1 at uhub3 port 3 configuration 1 interface 1
uhidev1: Microsoft NaturalM-BM-. Ergonomic Keyboard 4000, rev 2.00/1.73, addr 4, iclass 3/0
uhidev1: 1 report ids
uhid0 at uhidev1 reportid 1: input=7, output=0, feature=0

The net result is that, right now, these keyboards work as far as the
standard 104-key mapping is involved. However, *all* other keys have
now been moved to the generic uhid device, where they generate 

Microsoft thinks that they're DTRT, and even put out design guidelines
about this, if I'm to believe

This makes me believe that this situation is probably not going to be
a one-off situation that will resolve itself, and that more of these 
keyboards will be showing up in the near future.
As far as I know, the only way to deal with these events right now is
usbhidaction(1), which can execute programs when these events occur.

While this actually makes sense for some of these keys in some 
situations (volume+/-, mute, although this is a matter of personal
preferences) it is not suitable for many others. Keys like "back", "
forward", "search", "web/home", "mail" and "calculator" come to mind: 
desktop environments know how to handle these keys if only they would 
get keyboard events for them, but right now they don't.

I want to stress that this is a regression from the previous situation,
where most of these keys would generate scancodes, even if these scancodes
were not particulary well-defined and often varied from manufacturer to
manufacturer. Nothing xmodmap couldn't fix, though.

I've been giving this some thought, and I can come up with four ways to
deal with this. I'll work these out below. This got a bit longer than I
planned it to be, I'm sorry if I'm rambling.

1. Implement a specific driver for these uhid devices 
2. Make ukbd handle these additional uhid devices
3. Have usbhidaction deal with it by allowing it to generate wskbd events
4. The brilliant and blatantly obvious way 

1) Implement a specific driver for these uhid devices, which could register
   itself as a kind of wskbd device, attaching to the same mux as the 
   "QWERTY"-part of the keyboard. 

   Pro:  - If it looks like a keyboard and it quacks like a keyboard...
	 - Linux does this. You'd assume they gave it some thought. 

	 - Simple driver, in all probability
	 - It fits the design. Or at least, it doesn't stick out like
	   a sore thumb.
	 - Things would Just Work. 

   Con:  - Some people may actually prefer using uhidaction for some
           individual keys
	 - Done the Linux-way, which seems to be a little bit offhand, 
	   this might result in dozens of drivers for individual
	   keyboards, which is hardly desirable.
         - Preventing the above might be difficult, as device manufacturers
	   have a lot of freedom in their implementation. For example,
	   my keyboard has sane mappings in the "Consumer" table of the USB hid
	   usage table (See /usr/share/misc/usb_hid_usages, line 528 and
	   below), it also contains keys that are apperently Microsoft-
	   specific. These return as bits in a single uhid-register:
	   Either way, it would probably require a keymap of some sorts.
	 - Distinguishing between these multimedia-keyboard-uhid devices
	   and other generic uhid devices might be tricky; Microsoft Windows
	   obviously does it (It supported many of the extended keys without
	   installing any software; it only needed it for the Microsoft-
	   specific keys); I wouldn't be surprised if they merely recognise
	   it by the fact that it's a composite device with a regular 
	   keyboard HID. I'm not sore it's going to be easy to teach
	   autoconf about this. Of course, there's always to option of
	   specifying specific product/vendor combo's, but I was hoping for
	   a generic approach.
2. Make ukbd handle these additional uhid devices. A bad idea, IMHO,
   but I might be wrong.

   Pro: - All of the above.
        - It would resemble the PS/2 multimedia keyboard situation
	- A single device, no confusing mux entries
   Con: - All of the above, and then some
        - It violates the device tree. Since to my best knowledge 
	  NetBSD doesn't have a "possibly composite USB device" 
	  abstraction layer, it would mean combining leaf nodes that
	  have grown apart considerably already. It just doesn't feel
	- Why change ukbd, when it's not broken?

3. Have usbhidaction deal with it by allowing it to generate wskbd events

   Pro: - Existing functionality of usbhidaction can be reused, including
          dealing with unknown USB HID usage table entries
	- Considering that these keys are usually not pressed very often,
	  performance isn't that much of an issue
	- It would allow individual keys to be treated the way they are
	  treated now
	- Works for *all* uhid devices, not just these newfangled 
	- Very flexible; easy to adapt to new devices

   Con: - AFAIK, there is currently no way to introduce wskbd events 
          from userland at all, and such an interface would probably have
	  a very negative impact on security. It is opening the door to 
	  dozens of new angles of attack.
4. The brilliant and blatantly obvious way that I'm just too blind too see
   Pro: - It's brilliant and blatantly obvious. 
   Con: - It's been eluding me.

Any thoughts? Once again, I'm sorry for rambling.


Martijn van Buul -