[PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Henrique de Moraes Holschuh]

We have all the pieces needed to have sane, generic userland keyboard handling
in place for a while now, but it was not sufficiently documented (or used!).

If EV_KEY input drivers always generate scan codes that can be used to
reprogram their keycode maps, and always generate EV_MSC MSC_SCAN events when
they output an EV_KEY KEY_UNKNOWN event, userspace can trap those and feed it
to a generic helper that can ask the user to assign a key code and function to
that key.

This patch documents the requirements and best practices for EV_KEY input
drivers.

Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
---

 Dmitry, how is that as a first approximation of the text?

 Documentation/input/input-programming.txt |   53 ++++++++++++++++++++++++++++-
 1 files changed, 52 insertions(+), 1 deletions(-)

diff --git a/Documentation/input/input-programming.txt b/Documentation/input/input-programming.txt
index d9d5230..836f0bb 100644
--- a/Documentation/input/input-programming.txt
+++ b/Documentation/input/input-programming.txt
@@ -272,7 +272,58 @@ present, it is broken sometimes (at keyboards: Toshiba notebooks). To enable
 autorepeat for your device, just set EV_REP in dev->evbit. All will be
 handled by the input system.
 
-1.9 Other event types, handling output events
+1.9 Being friendly to userspace when implementing EV_KEY drivers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Input drivers that generate EV_KEY events should always support either
+dev->getkeycode()/dev->setkeycode(), or keycode, keycodemax and keycodesize,
+so as to allow userspace to reprogram the keycodes as needed.  They should
+also either always generate EV_MSC MSC_SCAN events along with every EV_KEY
+event, or special case EV_KEY KEY_UNKNOWN as described below.
+
+If the input driver doesn't support any of the generic methods to manipulate
+the keycode map, it must never issue a EV_KEY KEY_UNKNOWN event.  If you
+need to issue EV_KEY KEY_UNKNOWN events, please implement the code in your
+driver to manipulate its keycode map.  KEY_UNKNOWN is meant to be something
+that can be replaced by the user with a functional keycode.
+
+If the input driver generates an EV_KEY KEY_UNKNOWN event, it should also
+generate *in the same event block* (i.e. before it issues an EV_SYN) an
+EV_MSC MSC_SCAN event, with the scan code for the "unknown key".  This
+should be done both in "press" and "release" EV_KEY events.  The EV_MSC
+MSC_SCAN event allows a generic userspace keyboard helper daemon to ask the
+user if he would like to map a key in a input device to a valid keycode, and
+assign a function to it.
+
+The scan code of a key (as informed in a EV_MSC MSC_SCAN event) must be its
+index in the keycode map, as implemented by dev->getkeycode() /
+dev->setkeycode(), or keycode, keycodemax and keycodesize for the device.
+
+If a key has a specific function that is known to the driver, it should
+generate the appropriate keycode for that function by default.  E.g., in a
+laptop where the FN+F1 key combination is always marked "HELP" in the
+keyboard, the driver is to generate KEY_HELP and not KEY_FN_F1.
+
+Unmarked keys that do not have a set function, or whose functions are
+unknown, should usually generate by default an EV_KEY KEY_UNKNOWN event.  If
+a positional keycode for that key already exists in input.h (e.g. KEY_FN_F1
+for FN+F1), it can also be used for backwards compatibility.  KEY_UNKNOWN is
+preferred for all new drivers, however.
+
+Non-positional keycodes like KEY_PROG1 should never be used by default.
+
+As an example, a ThinkPad T43 laptop hot key keyboard has FN+F1 unmarked,
+and FN+F5 marked with a "RF transmitter" symbol.  The driver for this
+keyboard is to generate EV_KEY KEY_UNKNOWN (plus EV_MSC MSC_SCAN <fn+f1
+scancode>) if the user presses or releases FN+F1.  It could generate EV_KEY
+KEY_FN_F1 *instead* of EV_KEY KEY_UNKNOWN as well.
+
+If the ThinkPad T43 user presses FN+F5, however, the driver is to generate
+EV_KEY KEY_WLAN, and not KEY_FN_F5 or KEY_UNKNOWN (this assumes the driver
+does know it is running on a ThinkPad T43, and that it has a model-specific
+key table for the T43).
+
+1.10 Other event types, handling output events
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The other event types up to now are:
-- 
1.5.1.6


-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Matthew Garrett]

On Thu, May 31, 2007 at 07:28:14PM -0300, Henrique de Moraes Holschuh wrote:
> We have all the pieces needed to have sane, generic userland keyboard handling
> in place for a while now, but it was not sufficiently documented (or used!).
> 
> If EV_KEY input drivers always generate scan codes that can be used to
> reprogram their keycode maps, and always generate EV_MSC MSC_SCAN events when
> they output an EV_KEY KEY_UNKNOWN event, userspace can trap those and feed it
> to a generic helper that can ask the user to assign a key code and function to
> that key.

I still disagree that this is the best approach. Userspace already has 
the functionality to map keys if they produce a keycode. Producing 
KEY_UNKNOWN would require the implementation of a stack of extra code.

-- 
Matthew Garrett | mjg59@srcf.ucam.org

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Henrique de Moraes Holschuh]

On Fri, 01 Jun 2007, Matthew Garrett wrote:
> On Thu, May 31, 2007 at 07:28:14PM -0300, Henrique de Moraes Holschuh wrote:
> > We have all the pieces needed to have sane, generic userland keyboard handling
> > in place for a while now, but it was not sufficiently documented (or used!).
> > 
> > If EV_KEY input drivers always generate scan codes that can be used to
> > reprogram their keycode maps, and always generate EV_MSC MSC_SCAN events when
> > they output an EV_KEY KEY_UNKNOWN event, userspace can trap those and feed it
> > to a generic helper that can ask the user to assign a key code and function to
> > that key.
> 
> I still disagree that this is the best approach. Userspace already has 
> the functionality to map keys if they produce a keycode. Producing 
> KEY_UNKNOWN would require the implementation of a stack of extra code.

Well, we already produce KEY_UNKNOWN anyway, and the stuff you quoted above
just makes KEY_UNKNOWN useful for something instead of keeping it as an
useless notice to the user that some key (which one? who knows!) was
pressed.

Drivers already have KEY_RESERVED to mark positions in the keycode map for
keys that should generate no events, so we are not forcing anyone to always
generate useless events, either.

Perhaps what you dislike re. KEY_UNKNOWN is the part where KEY_UNKNOWN+scan
code is declared to be the prefered way to report keys that do not have a
specific function?  Your reply seems to indicate this, but I am not sure I
really understood what you meant.

I am not exactly in love with the idea of using KEY_UNKNOWN in place of
stuff like KEY_FN_F1 either (I'd prefer to just bump up KEY_MAX and have
more posicional keycodes), but Dmitry is being quite clear that he does not
want to increase KEY_MAX to add more positional keycodes.

-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Matthew Garrett]

On Thu, May 31, 2007 at 09:13:04PM -0300, Henrique de Moraes Holschuh wrote:

> Well, we already produce KEY_UNKNOWN anyway, and the stuff you quoted above
> just makes KEY_UNKNOWN useful for something instead of keeping it as an
> useless notice to the user that some key (which one? who knows!) was
> pressed.

Given existing userspace, it's never useful to generate KEY_UNKNOWN. 
Adding extra information to the event doesn't alter that.

> Perhaps what you dislike re. KEY_UNKNOWN is the part where KEY_UNKNOWN+scan
> code is declared to be the prefered way to report keys that do not have a
> specific function?  Your reply seems to indicate this, but I am not sure I
> really understood what you meant.

Yes.

> I am not exactly in love with the idea of using KEY_UNKNOWN in place of
> stuff like KEY_FN_F1 either (I'd prefer to just bump up KEY_MAX and have
> more posicional keycodes), but Dmitry is being quite clear that he does not
> want to increase KEY_MAX to add more positional keycodes.

I think using positional keycodes would also be a mistake. We just need 
a slightly larger set of keycodes representing user-definable keys. 
There's 4 of them already - I really can't imagine there being many 
keyboards with a significantly larger set of unlabelled keys.

-- 
Matthew Garrett | mjg59@srcf.ucam.org

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Henrique de Moraes Holschuh]

On Fri, 01 Jun 2007, Matthew Garrett wrote:
> On Thu, May 31, 2007 at 09:13:04PM -0300, Henrique de Moraes Holschuh wrote:
> > Well, we already produce KEY_UNKNOWN anyway, and the stuff you quoted above
> > just makes KEY_UNKNOWN useful for something instead of keeping it as an
> > useless notice to the user that some key (which one? who knows!) was
> > pressed.
> 
> Given existing userspace, it's never useful to generate KEY_UNKNOWN. 
> Adding extra information to the event doesn't alter that.

It will not break anything, and it is trivial to write an application to
intelligently handle KEY_UNKNOWN+scancode events.  This really is not a
reason to not do it, at all.

> > Perhaps what you dislike re. KEY_UNKNOWN is the part where KEY_UNKNOWN+scan
> > code is declared to be the prefered way to report keys that do not have a
> > specific function?  Your reply seems to indicate this, but I am not sure I
> > really understood what you meant.
> 
> Yes.

That could easily be removed or switched around but...

> > I am not exactly in love with the idea of using KEY_UNKNOWN in place of
> > stuff like KEY_FN_F1 either (I'd prefer to just bump up KEY_MAX and have
> > more posicional keycodes), but Dmitry is being quite clear that he does not
> > want to increase KEY_MAX to add more positional keycodes.
> 
> I think using positional keycodes would also be a mistake. We just need 
> a slightly larger set of keycodes representing user-definable keys. 
> There's 4 of them already - I really can't imagine there being many 
> keyboards with a significantly larger set of unlabelled keys.

I had this exact PoV, too, until Dmitry reminded me that keycodes are
*global* to the system in practice, and that different keys (as in keys that
have no correlation between their position, labels or lack thereof, and
function) in different input devices would end up mapped to KEY_PROGx by
default.

And in that scenario, KEY_UNKNOWN (i.e. "please remap me to what you want
this key to do for real") makes a lot more sense, given that we don't have
all the positional keycodes we need, and more are not being added.

-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Matthew Garrett]

On Thu, May 31, 2007 at 10:29:28PM -0300, Henrique de Moraes Holschuh wrote:
> On Fri, 01 Jun 2007, Matthew Garrett wrote:
> > Given existing userspace, it's never useful to generate KEY_UNKNOWN. 
> > Adding extra information to the event doesn't alter that.
> 
> It will not break anything, and it is trivial to write an application to
> intelligently handle KEY_UNKNOWN+scancode events.  This really is not a
> reason to not do it, at all.

It's not trivial at all. You need to introduce a mechanism for noting a 
KEY_UNKNOWN keypress. It then needs to signal the user (dbus is probably 
the best layer for this), but you need to ensure that you only signal 
the user who is currently at the keyboard. This needs to be presented to 
the user via some sort of UI, which will then need to signal some sort 
of privileged process to actually change the keymap. When the user logs 
out, you'll then need to unmap the key again and repeat as necessary for 
any new user who logs in.

Alternatively, we could generate a keycode and then let the user map 
that to an X keysym. We've even already got code to do this.

> > I think using positional keycodes would also be a mistake. We just need 
> > a slightly larger set of keycodes representing user-definable keys. 
> > There's 4 of them already - I really can't imagine there being many 
> > keyboards with a significantly larger set of unlabelled keys.
> 
> I had this exact PoV, too, until Dmitry reminded me that keycodes are
> *global* to the system in practice, and that different keys (as in keys that
> have no correlation between their position, labels or lack thereof, and
> function) in different input devices would end up mapped to KEY_PROGx by
> default.

That's a ridiculously niche case, and can be handled in userspace. Just 
have udev do remapping when it detects multiple keyboards that both have 
KEY_PROG* layers, or let X have different keymaps for different input 
devices. We shouldn't make the (by far) common case significantly more 
difficult to deal with this one.

-- 
Matthew Garrett | mjg59@srcf.ucam.org

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Henrique de Moraes Holschuh]

On Fri, 01 Jun 2007, Matthew Garrett wrote:
> On Thu, May 31, 2007 at 10:29:28PM -0300, Henrique de Moraes Holschuh wrote:
> > On Fri, 01 Jun 2007, Matthew Garrett wrote:
> > > Given existing userspace, it's never useful to generate KEY_UNKNOWN. 
> > > Adding extra information to the event doesn't alter that.
> > 
> > It will not break anything, and it is trivial to write an application to
> > intelligently handle KEY_UNKNOWN+scancode events.  This really is not a
> > reason to not do it, at all.
> 
> It's not trivial at all. You need to introduce a mechanism for noting a 
> KEY_UNKNOWN keypress. It then needs to signal the user (dbus is probably 

That would be trivial, but...

> the best layer for this), but you need to ensure that you only signal 
> the user who is currently at the keyboard. This needs to be presented to 
> the user via some sort of UI, which will then need to signal some sort 
> of privileged process to actually change the keymap. When the user logs 
> out, you'll then need to unmap the key again and repeat as necessary for 
> any new user who logs in.

... this is not.  You're correct.  So using KEY_UNKNOWN should not be the
preferred way, then.

> Alternatively, we could generate a keycode and then let the user map 
> that to an X keysym. We've even already got code to do this.

Well, I also would appreciate bumping up KEY_MAX and a nice shiny set of
KEY_FN that covered all the missing ones for ThinkPads.  It is Dmitry you
have to convince about it.

That still doesn't make KEY_UNKNOWN without a scan code useful, so either
way, I think KEY_UNKNOWN should be limited to drivers that can remap
keycodes *and* which send MSC_SCAN events along with KEY_UNKNOWN, so that
you know what key to remap.  I don't care if it is easy or not to be nice to
the user and ask for a key remap, at least it will not be *impossible* like
it currently is.  Otherwise, we would be better off removing KEY_UNKNOWN
altogether (which I wouldn't mind much, either).

> > > I think using positional keycodes would also be a mistake. We just need 
> > > a slightly larger set of keycodes representing user-definable keys. 
> > > There's 4 of them already - I really can't imagine there being many 
> > > keyboards with a significantly larger set of unlabelled keys.
> > 
> > I had this exact PoV, too, until Dmitry reminded me that keycodes are
> > *global* to the system in practice, and that different keys (as in keys that
> > have no correlation between their position, labels or lack thereof, and
> > function) in different input devices would end up mapped to KEY_PROGx by
> > default.
> 
> That's a ridiculously niche case, and can be handled in userspace. Just 
> have udev do remapping when it detects multiple keyboards that both have 
> KEY_PROG* layers, or let X have different keymaps for different input 
> devices. We shouldn't make the (by far) common case significantly more 
> difficult to deal with this one.

Dmitry?

-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Dmitry Torokhov]

On Thursday 31 May 2007 21:44, Matthew Garrett wrote:
> On Thu, May 31, 2007 at 10:29:28PM -0300, Henrique de Moraes Holschuh wrote:
> > On Fri, 01 Jun 2007, Matthew Garrett wrote:
> > > Given existing userspace, it's never useful to generate KEY_UNKNOWN. 
> > > Adding extra information to the event doesn't alter that.
> > 
> > It will not break anything, and it is trivial to write an application to
> > intelligently handle KEY_UNKNOWN+scancode events.  This really is not a
> > reason to not do it, at all.
> 
> It's not trivial at all. You need to introduce a mechanism for noting a 
> KEY_UNKNOWN keypress. It then needs to signal the user (dbus is probably 
> the best layer for this), but you need to ensure that you only signal 
> the user who is currently at the keyboard. This needs to be presented to 
> the user via some sort of UI, which will then need to signal some sort 
> of privileged process to actually change the keymap.

Not necessarily priveleged - you most likely already change ownership
of event devices to user who is logged at console (so your force feedback
joysticks work).

> When the user logs  
> out, you'll then need to unmap the key again and repeat as necessary for 
> any new user who logs in.

I think we should aim at the most common case - when there are no multiple
users on the box. Then the utility that detects KEY_UNKNOWN just saves the
mapping user chose and automatically reload keymap upon next reboot.

Note that KEY_UNKNOWN solution does not preculde futher customization on
per-user base once default action is established.

> 
> Alternatively, we could generate a keycode and then let the user map 
> that to an X keysym. We've even already got code to do this.
>

There is world outside of X.
 
> > > I think using positional keycodes would also be a mistake. We just need 
> > > a slightly larger set of keycodes representing user-definable keys. 
> > > There's 4 of them already - I really can't imagine there being many 
> > > keyboards with a significantly larger set of unlabelled keys.
> > 
> > I had this exact PoV, too, until Dmitry reminded me that keycodes are
> > *global* to the system in practice, and that different keys (as in keys that
> > have no correlation between their position, labels or lack thereof, and
> > function) in different input devices would end up mapped to KEY_PROGx by
> > default.
> 
> That's a ridiculously niche case, and can be handled in userspace. Just 
> have udev do remapping when it detects multiple keyboards that both have 
> KEY_PROG* layers, or let X have different keymaps for different input 
> devices. We shouldn't make the (by far) common case significantly more 
> difficult to deal with this one.
> 

No, it is not a niche case. I think it is much more common than the case where
you have multiple users for the same box using different keymaps. Even if box
is shared there most likely will be one person setting it up in the beginning
and the rest will follow his/her setup.

-- 
Dmitry

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Matthew Garrett]

On Thu, May 31, 2007 at 11:33:10PM -0400, Dmitry Torokhov wrote:
> On Thursday 31 May 2007 21:44, Matthew Garrett wrote:
> > It's not trivial at all. You need to introduce a mechanism for noting a 
> > KEY_UNKNOWN keypress. It then needs to signal the user (dbus is probably 
> > the best layer for this), but you need to ensure that you only signal 
> > the user who is currently at the keyboard. This needs to be presented to 
> > the user via some sort of UI, which will then need to signal some sort 
> > of privileged process to actually change the keymap.
> 
> Not necessarily priveleged - you most likely already change ownership
> of event devices to user who is logged at console (so your force feedback
> joysticks work).

If you let users alter the kernel keymap, then you need to implement 
support for resetting the kernel keymap on exit. Otherwise it's a 
trivial DoS.

> > When the user logs  
> > out, you'll then need to unmap the key again and repeat as necessary for 
> > any new user who logs in.
> 
> I think we should aim at the most common case - when there are no multiple
> users on the box. Then the utility that detects KEY_UNKNOWN just saves the
> mapping user chose and automatically reload keymap upon next reboot.

The standard setup for home machines tends to be an account per family 
member. The standard setup in an office environment is likely to be 
multiuser.

> Note that KEY_UNKNOWN solution does not preculde futher customization on
> per-user base once default action is established.

No, but it makes it significantly more confusing. User 1 chooses a 
setup. This gets saved. User 2 remaps keys based on User 1's settings 
(which have been restored at bootup). User 1 alters key mapping. User 2 
suddenly becomes hugely confused.

> > 
> > Alternatively, we could generate a keycode and then let the user map 
> > that to an X keysym. We've even already got code to do this.
> >
> 
> There is world outside of X.

On machines like we're discussing (laptops, basically) it's a tiny 
world. Optimise for the common case, not the rare one.

> > That's a ridiculously niche case, and can be handled in userspace. Just 
> > have udev do remapping when it detects multiple keyboards that both have 
> > KEY_PROG* layers, or let X have different keymaps for different input 
> > devices. We shouldn't make the (by far) common case significantly more 
> > difficult to deal with this one.
> > 
> 
> No, it is not a niche case. I think it is much more common than the case where
> you have multiple users for the same box using different keymaps. Even if box
> is shared there most likely will be one person setting it up in the beginning
> and the rest will follow his/her setup.

How many users plug external keyboards with unlabelled keys into a 
laptop? No, I really don't think that's a common case at all.

The solution that satisfies the largest number of users with the 
smallest amount of work is the one where pressing a key on the keyboard 
results in X events being generated. Right now, that requires that the 
key generate a real keycode.

-- 
Matthew Garrett | mjg59@srcf.ucam.org

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Dmitry Torokhov]

On Friday 01 June 2007 00:08, Matthew Garrett wrote:
> On Thu, May 31, 2007 at 11:33:10PM -0400, Dmitry Torokhov wrote:
> > On Thursday 31 May 2007 21:44, Matthew Garrett wrote:
> > > It's not trivial at all. You need to introduce a mechanism for noting a 
> > > KEY_UNKNOWN keypress. It then needs to signal the user (dbus is probably 
> > > the best layer for this), but you need to ensure that you only signal 
> > > the user who is currently at the keyboard. This needs to be presented to 
> > > the user via some sort of UI, which will then need to signal some sort 
> > > of privileged process to actually change the keymap.
> > 
> > Not necessarily priveleged - you most likely already change ownership
> > of event devices to user who is logged at console (so your force feedback
> > joysticks work).
> 
> If you let users alter the kernel keymap, then you need to implement 
> support for resetting the kernel keymap on exit. Otherwise it's a 
> trivial DoS.
> 

You already do - do you let your users play games with force-feedback
joysticks? To load force feedback effect you need write permissions for
corresponding event device.

And we are talking about console owner here - with current desktop-oriented
distributions they already get access to host of otherwise restricted
devices.

> > > When the user logs  
> > > out, you'll then need to unmap the key again and repeat as necessary for 
> > > any new user who logs in.
> > 
> > I think we should aim at the most common case - when there are no multiple
> > users on the box. Then the utility that detects KEY_UNKNOWN just saves the
> > mapping user chose and automatically reload keymap upon next reboot.
> 
> The standard setup for home machines tends to be an account per family 
> member.

That could be... Although it is desktops that are usually shared.
Hmm, I am trying to remember setup of the people I know... I think
the most common setup is a desktop in an easily accessible place
(kitchen) with a single account. Older kids/parents may have their
own desktop/laptops that are not shared.

> The standard setup in an office environment is likely to be  
> multiuser.

Huh? In my limited experience everyone in the office gets its own box.
And I am not talking about software shop.

> 
> > Note that KEY_UNKNOWN solution does not preculde futher customization on
> > per-user base once default action is established.
> 
> No, but it makes it significantly more confusing. User 1 chooses a 
> setup. This gets saved. User 2 remaps keys based on User 1's settings 
> (which have been restored at bootup). User 1 alters key mapping. User 2 
> suddenly becomes hugely confused.

One user is an administrator. He can alter the global keymap. If there
are multiple users he may need to be cautious.
 
> > > 
> > > Alternatively, we could generate a keycode and then let the user map 
> > > that to an X keysym. We've even already got code to do this.
> > >
> > 
> > There is world outside of X.
> 
> On machines like we're discussing (laptops, basically) it's a tiny 
> world. Optimise for the common case, not the rare one.
> 
> > > That's a ridiculously niche case, and can be handled in userspace. Just 
> > > have udev do remapping when it detects multiple keyboards that both have 
> > > KEY_PROG* layers, or let X have different keymaps for different input 
> > > devices. We shouldn't make the (by far) common case significantly more 
> > > difficult to deal with this one.
> > > 
> > 
> > No, it is not a niche case. I think it is much more common than the case where
> > you have multiple users for the same box using different keymaps. Even if box
> > is shared there most likely will be one person setting it up in the beginning
> > and the rest will follow his/her setup.
> 
> How many users plug external keyboards with unlabelled keys into a 
> laptop? No, I really don't think that's a common case at all.

I think quite a few people use external keyboards. I know that in my office
everyone with a laptop has a docking station and uses full keyboard with
it. I use external AT keyboard at home...

As far as unlabeled goes - they may be labeled but we may not know their
labels.

> The solution that satisfies the largest number of users with the 
> smallest amount of work is the one where pressing a key on the keyboard 
> results in X events being generated. Right now, that requires that the 
> key generate a real keycode.
> 

Again, it is not only about X. What if X is not running (or running but
nobody is logged in)? There are number of events (SUSPEND, WLAN switch,
undock request, etc) that should be handled by daemons not depending
on X.

-- 
Dmitry

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Matthew Garrett]

On Fri, Jun 01, 2007 at 12:37:58AM -0400, Dmitry Torokhov wrote:
> On Friday 01 June 2007 00:08, Matthew Garrett wrote:
> > If you let users alter the kernel keymap, then you need to implement 
> > support for resetting the kernel keymap on exit. Otherwise it's a 
> > trivial DoS.
> > 
> 
> You already do - do you let your users play games with force-feedback
> joysticks? To load force feedback effect you need write permissions for
> corresponding event device.

That's much less of a problem, especially since (realistically) any 
force feedback-aware application will reset the values on first use. 
That's not the case for the keymap.

> > The standard setup in an office environment is likely to be  
> > multiuser.
> 
> Huh? In my limited experience everyone in the office gets its own box.
> And I am not talking about software shop.

Standard is that everyone gets their own machine, but usually everyone 
has an account on all of them.

> > No, but it makes it significantly more confusing. User 1 chooses a 
> > setup. This gets saved. User 2 remaps keys based on User 1's settings 
> > (which have been restored at bootup). User 1 alters key mapping. User 2 
> > suddenly becomes hugely confused.
> 
> One user is an administrator. He can alter the global keymap. If there
> are multiple users he may need to be cautious.

Or we could just leave the mapping up to individual users, which avoids 
the problem.

> > How many users plug external keyboards with unlabelled keys into a 
> > laptop? No, I really don't think that's a common case at all.
> 
> I think quite a few people use external keyboards. I know that in my office
> everyone with a laptop has a docking station and uses full keyboard with
> it. I use external AT keyboard at home...
> 
> As far as unlabeled goes - they may be labeled but we may not know their
> labels.

If a key is labelled in a non-generic way then it shouldn't generate 
KEY_PROGwhatever. That's a separate problem.

> > The solution that satisfies the largest number of users with the 
> > smallest amount of work is the one where pressing a key on the keyboard 
> > results in X events being generated. Right now, that requires that the 
> > key generate a real keycode.
> > 
> 
> Again, it is not only about X. What if X is not running (or running but
> nobody is logged in)? There are number of events (SUSPEND, WLAN switch,
> undock request, etc) that should be handled by daemons not depending
> on X.

The existing implementations use X. I don't think any of the desktop 
distributions really care about the non-X case for this sort of thing.
-- 
Matthew Garrett | mjg59@srcf.ucam.org

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Dmitry Torokhov]

On 6/1/07, Matthew Garrett <mjg59@srcf.ucam.org> wrote:
> On Fri, Jun 01, 2007 at 12:37:58AM -0400, Dmitry Torokhov wrote:
> > On Friday 01 June 2007 00:08, Matthew Garrett wrote:
> > > If you let users alter the kernel keymap, then you need to implement
> > > support for resetting the kernel keymap on exit. Otherwise it's a
> > > trivial DoS.
> > >
> >
> > You already do - do you let your users play games with force-feedback
> > joysticks? To load force feedback effect you need write permissions for
> > corresponding event device.
>
> That's much less of a problem, especially since (realistically) any
> force feedback-aware application will reset the values on first use.
> That's not the case for the keymap.
>

What I am trying to say - there already EVIOCSKEYCODE ioctl in the
kernel. And for force feedback devices to work you need to nable
writing to corresponding /dev/input/eventX thus opening possibility to
alter the keymap table. I guess you coudl analyze capabilities of a
device and only relax permissions for devices that have FF...

Anyway, I think that we don't want ordinary users to alter hardware
keymapping, it should indeed be priveleged operation done by box's
administrator. Hopefully the infrastructure (hal/udev/whatever) will
be able to load proper keymap at boot time so even that is not needed.

Why I think using kernel remapping_in addition_ to X remapping is better:

- X remapping only works in X. Even if you say that major
distributions presently moved all logic in X but I don't think it is
the only true way (in fact I think that some of it should run as
standalone daemons; if I press power button I want my box to shut down
even if I happen to be at text console. Same goes for sleep).

- KEY_PROG* are assigned somewhat randomly across devices, with
KEY_PROG1 matching FN-F1 on laptop multimedia key and also on one of
the buttons on that remote control that manufacturers tend to supply
with those "desktop replacement" laptops. Remapping them in X will not
satisfy user. However remappig into actions (like KEY_EJECTCD) on
kernel level solves this. From user perspective there isn't really any
difference - he assigns an action to a key.

- Having devices generate KEY_UNKNOWN with a nice dialog box
explaining what had happened will alert users of existance of events
generated by such (esp. if they are unlabeled and hit by accident).
For labeled keys we may ask user to submit necessary data to one of
the projects (HAL?) to add to the database of devices/models/keymaps.
If we were generating KEY_PROG1 more sophisticated users would simply
remap the keys and move on without telling anybody.

- If using X remapping alone every user will have to repeat the task
of mapping keycodes. In case when there are labels on the keyboard
(but the kernel does not know what it is) that setup is likely to be
identical for most users on the box. I venture to say that even with
unlabeled keys the setup will be identical - first user will influence
the rest.

The biggest cons for KEY_UNKNOWN + scancode is that presently we do
not have the code to iteract with user.

> > > The standard setup in an office environment is likely to be
> > > multiuser.
> >
> > Huh? In my limited experience everyone in the office gets its own box.
> > And I am not talking about software shop.
>
> Standard is that everyone gets their own machine, but usually everyone
> has an account on all of them.

Which is never used (except remotely)...

-- 
Dmitry

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Matthew Garrett]

On Fri, Jun 01, 2007 at 10:04:56AM -0400, Dmitry Torokhov wrote:

> Anyway, I think that we don't want ordinary users to alter hardware
> keymapping, it should indeed be priveleged operation done by box's
> administrator. Hopefully the infrastructure (hal/udev/whatever) will
> be able to load proper keymap at boot time so even that is not needed.

Any solution which involves a naive user pressing a key and a dialog 
appearing saying "Please enter the administrator password to map this 
key" is not a satisfactory solution. 

> - X remapping only works in X. Even if you say that major
> distributions presently moved all logic in X but I don't think it is
> the only true way (in fact I think that some of it should run as
> standalone daemons; if I press power button I want my box to shut down
> even if I happen to be at text console. Same goes for sleep).

That's simply not a use-case we (or, as far as I can tell, any of the 
other major distributions) are interested in. It's very difficult to 
come up with a method for providing per-user policy without it depending 
on X.

> - KEY_PROG* are assigned somewhat randomly across devices, with
> KEY_PROG1 matching FN-F1 on laptop multimedia key and also on one of
> the buttons on that remote control that manufacturers tend to supply
> with those "desktop replacement" laptops. Remapping them in X will not
> satisfy user. However remappig into actions (like KEY_EJECTCD) on
> kernel level solves this. From user perspective there isn't really any
> difference - he assigns an action to a key.

Producing KEY_PROG* by default doesn't prevent this in any way. With the 
exception of the PS/2 keyboard nightmare, we're always able to 
distinguish between different input devices and remap them if necessary. 
It's fine to require extra complexity for more complicated cases. That 
doesn't mean it's worth requiring that complexity for all cases.

> - If using X remapping alone every user will have to repeat the task
> of mapping keycodes. In case when there are labels on the keyboard
> (but the kernel does not know what it is) that setup is likely to be
> identical for most users on the box. I venture to say that even with
> unlabeled keys the setup will be identical - first user will influence
> the rest.

That problem is already solved at the desktop level.

> The biggest cons for KEY_UNKNOWN + scancode is that presently we do
> not have the code to iteract with user.

It's a large pile of code and it's going to have to be implemented 
multiple times in order to integrate with the different desktop 
environments. I really don't think it's worth it.
-- 
Matthew Garrett | mjg59@srcf.ucam.org

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Henrique de Moraes Holschuh]

On Fri, 01 Jun 2007, Dmitry Torokhov wrote:
> On 6/1/07, Matthew Garrett <mjg59@srcf.ucam.org> wrote:
> What I am trying to say - there already EVIOCSKEYCODE ioctl in the
> kernel. And for force feedback devices to work you need to nable
> writing to corresponding /dev/input/eventX thus opening possibility to
> alter the keymap table. I guess you coudl analyze capabilities of a
> device and only relax permissions for devices that have FF...

Agreed. CAP_SYSADMIN or somesuch should be required for some of those
IOCTLs, at least on keyboards. I don't see a problem with a digitizing
tablet relaxing that to allow anyone, for example, so it makes sense to punt
this test to the driver level (and not input layer level), or to make it
configurable somehow from the driver level before registering the input
device.

> Anyway, I think that we don't want ordinary users to alter hardware
> keymapping, it should indeed be priveleged operation done by box's
> administrator. Hopefully the infrastructure (hal/udev/whatever) will
> be able to load proper keymap at boot time so even that is not needed.
> 
> Why I think using kernel remapping_in addition_ to X remapping is better:

Agreed.

> The biggest cons for KEY_UNKNOWN + scancode is that presently we do
> not have the code to iteract with user.

Actually, it is more like "we don't have it, and it is non-trivial to do it
right", if I understood Matthew correctly.

> >> > The standard setup in an office environment is likely to be
> >> > multiuser.
> >>
> >> Huh? In my limited experience everyone in the office gets its own box.
> >> And I am not talking about software shop.
> >
> >Standard is that everyone gets their own machine, but usually everyone
> >has an account on all of them.
> 
> Which is never used (except remotely)...

Oh yes, it *is* used, and very much so.

-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Dmitry Torokhov]

On 6/1/07, Henrique de Moraes Holschuh <hmh@hmh.eng.br> wrote:
> On Fri, 01 Jun 2007, Dmitry Torokhov wrote:
> > On 6/1/07, Matthew Garrett <mjg59@srcf.ucam.org> wrote:
> > What I am trying to say - there already EVIOCSKEYCODE ioctl in the
> > kernel. And for force feedback devices to work you need to nable
> > writing to corresponding /dev/input/eventX thus opening possibility to
> > alter the keymap table. I guess you coudl analyze capabilities of a
> > device and only relax permissions for devices that have FF...
>
> Agreed. CAP_SYSADMIN or somesuch should be required for some of those
> IOCTLs, at least on keyboards. I don't see a problem with a digitizing
> tablet relaxing that to allow anyone, for example, so it makes sense to punt
> this test to the driver level (and not input layer level), or to make it
> configurable somehow from the driver level before registering the input
> device.

That is going to be a bitch to implement for HID devices which can be
all of the above at once.

>
> > Anyway, I think that we don't want ordinary users to alter hardware
> > keymapping, it should indeed be priveleged operation done by box's
> > administrator. Hopefully the infrastructure (hal/udev/whatever) will
> > be able to load proper keymap at boot time so even that is not needed.
> >
> > Why I think using kernel remapping_in addition_ to X remapping is better:
>
> Agreed.
>
> > The biggest cons for KEY_UNKNOWN + scancode is that presently we do
> > not have the code to iteract with user.
>
> Actually, it is more like "we don't have it, and it is non-trivial to do it
> right", if I understood Matthew correctly.
>

Yes, here I agree. There are quirks to be worked out.

There is one more thing. If we alias KEY_FN_ESC through KEY_FN_B as
KEY_GENACT* this will give us 20 general-purpose actions. If we add
something like EVIOGSCANCODE to retrieve reverse mapping then
distributions like Matthew's can just scan new input devices in udev
and remap to KEY_GENACT* while we employ KEY_UNKNOWN + scancode on
kernel level.

> > >> > The standard setup in an office environment is likely to be
> > >> > multiuser.
> > >>
> > >> Huh? In my limited experience everyone in the office gets its own box.
> > >> And I am not talking about software shop.
> > >
> > >Standard is that everyone gets their own machine, but usually everyone
> > >has an account on all of them.
> >
> > Which is never used (except remotely)...
>
> Oh yes, it *is* used, and very much so.

Ok, different experiences I guess...

-- 
Dmitry

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Henrique de Moraes Holschuh]

On Fri, 01 Jun 2007, Matthew Garrett wrote:
> Or we could just leave the mapping up to individual users, which avoids 
> the problem.

Other than the fact that it is not a piece of candy to implement correctly.

> > Again, it is not only about X. What if X is not running (or running but
> > nobody is logged in)? There are number of events (SUSPEND, WLAN switch,
> > undock request, etc) that should be handled by daemons not depending
> > on X.
> 
> The existing implementations use X. I don't think any of the desktop 
> distributions really care about the non-X case for this sort of thing.

Debian does, for one.  And I am pretty sure it is not the only one.

Also, let me state right now that IMO, this "I need X to be running and
logged in" for dock, eject, suspend, wlan on/off and other *system* level
activity to work is an extremely bad idea and broken on so many levels it is
not funny.

I have nothing against allowing such activities to be *modified* to suit the
logged in user, subject to approval by the system administrator.  But to
have them implemented in that level? Yuck.

But I don't see what this means for input device keyboard maps.  Any of the
proposed solutions to the problem so far will work equally well (or not well
:) ) for console and X users, even the "lots of KEY_UNKNOWN" one...

-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Henrique de Moraes Holschuh]

On Fri, 01 Jun 2007, Matthew Garrett wrote:
> On Thu, May 31, 2007 at 11:33:10PM -0400, Dmitry Torokhov wrote:
> > On Thursday 31 May 2007 21:44, Matthew Garrett wrote:
> > > It's not trivial at all. You need to introduce a mechanism for noting a 
> > > KEY_UNKNOWN keypress. It then needs to signal the user (dbus is probably 
> > > the best layer for this), but you need to ensure that you only signal 
> > > the user who is currently at the keyboard. This needs to be presented to 
> > > the user via some sort of UI, which will then need to signal some sort 
> > > of privileged process to actually change the keymap.
> > 
> > Not necessarily priveleged - you most likely already change ownership
> > of event devices to user who is logged at console (so your force feedback
> > joysticks work).
> 
> If you let users alter the kernel keymap, then you need to implement 
> support for resetting the kernel keymap on exit. Otherwise it's a 
> trivial DoS.

True, and unfortunately this is not something that can be done right with
what we have now and playing with udev.  Oh dear, I was too hasty to think
that we had all the infrastructure needed already...

Changing system-wide keymap should be a privileged operation.  Changing
per-user keymaps should not screw up any system-wide keymap changes made by
the administrator, and it needs to go away for the next user.

And for multi-user systems, you likely need to be able to switch keyboard
maps when VTs are switched.   This does not look like an easy thing to fix
properly.

The truth is that what we currently have seems suitable only for
system-administrator level changes (aka trusted, global changes), and should
be restricted to CAP_SYSADMIN.

> > I think we should aim at the most common case - when there are no multiple
> > users on the box. Then the utility that detects KEY_UNKNOWN just saves the
> > mapping user chose and automatically reload keymap upon next reboot.

I disagree.  It is one thing to do extremely broken optimizations like not
unloading heads on scsi disks "because it could be in a multiple initiator
system", thus breaking 99% of the systems out there.  It is a very different
thing to not support a multi-user system scenario at all re. keyboard maps.

I don't care if we default for single-user systems, but we definately have
to properly support the multi-user system case, and it *is* a very common
case in business workstations AND home user systems anywhere computers are
not as cheap as a ticket to the movies.

At the very least we need to protect the keymap from untrusted changes while
we don't have anything but system-wide ones.  And we should start working on
per-user (really, copy-on-write per-fd keymaps. Yuck!) or per-VT/pty keymaps
done safely, too.

> The standard setup for home machines tends to be an account per family 
> member. The standard setup in an office environment is likely to be 
> multiuser.

Agreed.  This is what I see in Brazil.  Most homes have only ONE computer,
when they have one at all.  And most office environments have one computer
per seat, and less seats than there are workers.

> > Note that KEY_UNKNOWN solution does not preculde futher customization on
> > per-user base once default action is established.
> 
> No, but it makes it significantly more confusing. User 1 chooses a 
> setup. This gets saved. User 2 remaps keys based on User 1's settings 
> (which have been restored at bootup). User 1 alters key mapping. User 2 
> suddenly becomes hugely confused.

Well, the proper fix for this has nothing to do with KEY_UNKNOWN, and it is
per-user/per-VT/pty keymaps and a reset IOCTL (or automatic reset in the
per-user case).

> > > Alternatively, we could generate a keycode and then let the user map 
> > > that to an X keysym. We've even already got code to do this.
> > >
> > 
> > There is world outside of X.
> 
> On machines like we're discussing (laptops, basically) it's a tiny 
> world. Optimise for the common case, not the rare one.

If the input system is going to start breaking The Console now, you can
expect to have me fighting you all the way.  I do agree that a
system-admin-only case for the console is good enough, though: multi user
systems that have to bother with per-user keymaps will be running X or
something like that.

> > > That's a ridiculously niche case, and can be handled in userspace. Just 
> > > have udev do remapping when it detects multiple keyboards that both have 
> > > KEY_PROG* layers, or let X have different keymaps for different input 
> > > devices. We shouldn't make the (by far) common case significantly more 
> > > difficult to deal with this one.
> > > 
> > 
> > No, it is not a niche case. I think it is much more common than the case where
> > you have multiple users for the same box using different keymaps. Even if box
> > is shared there most likely will be one person setting it up in the beginning
> > and the rest will follow his/her setup.
> 
> How many users plug external keyboards with unlabelled keys into a 
> laptop? No, I really don't think that's a common case at all.

Err... potentially a lot of them could.  Good laptop manufacturers sell
keyboards with the touchpad and hot keys matching the laptop, you know.  It
is what you get for The Boss to go with his shiny dock so that he doesn't
have to plug cables on the laptop, ever (you also get a matching set for his
home and send someone there to set it up for him).  Heck, for thinkpads I
could get even a keyboard with the touchpad and ultranav (the "nipple") if I
wanted!

And keyboards nowadays are *full* of weird keys, many of them unlabelled so
that "gamers" can assign them different functions...

Unlabelled keys are *common* these days.   What I agree to be uncommon is
two or more keyboards per machine with different users on them (i.e.
multi-head boxes), but that's just because Linux is starting to get really
friendly out-of-the-box to multi-head boxes now.  I know they would be using
them like crazy at work if it was something easier to set-up and maintain.

> The solution that satisfies the largest number of users with the 
> smallest amount of work is the one where pressing a key on the keyboard 
> results in X events being generated. Right now, that requires that the 
> key generate a real keycode.

Well, if key_unknown is a very very uncommon thing, we could have the
system-admin-only nature of keyboard remapping (thus avoiding DoS attacks on
multi-user systems). and be done with this.  But for that, we need KEY_MAX
bumped up.

-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN

[Helge Hafting]

Henrique de Moraes Holschuh wrote:
> On Fri, 01 Jun 2007, Matthew Garrett wrote:
>   
>> On Thu, May 31, 2007 at 11:33:10PM -0400, Dmitry Torokhov wrote:
>>     
>>> On Thursday 31 May 2007 21:44, Matthew Garrett wrote:
>>>       
>>>> It's not trivial at all. You need to introduce a mechanism for noting a 
>>>> KEY_UNKNOWN keypress. It then needs to signal the user (dbus is probably 
>>>> the best layer for this), but you need to ensure that you only signal 
>>>> the user who is currently at the keyboard. This needs to be presented to 
>>>> the user via some sort of UI, which will then need to signal some sort 
>>>> of privileged process to actually change the keymap.
>>>>         
>>> Not necessarily priveleged - you most likely already change ownership
>>> of event devices to user who is logged at console (so your force feedback
>>> joysticks work).
>>>       
>> If you let users alter the kernel keymap, then you need to implement 
>> support for resetting the kernel keymap on exit. Otherwise it's a 
>> trivial DoS.
>>     
>
> True, and unfortunately this is not something that can be done right with
> what we have now and playing with udev.  Oh dear, I was too hasty to think
> that we had all the infrastructure needed already...
>
> Changing system-wide keymap should be a privileged operation.  Changing
> per-user keymaps should not screw up any system-wide keymap changes made by
> the administrator, and it needs to go away for the next user.
>
> And for multi-user systems, you likely need to be able to switch keyboard
> maps when VTs are switched.   This does not look like an easy thing to fix
> properly.
>   
 From a design standpoint, keyboard layour should obviously
be a per-VT thing. One mapping table per VT, switching happening
automatically as every keypress gets filtered throught the
current VT.

Simple design, but perhaps that is more work than anyone
care to do on the current stuff. It can also be argued that the
actual keyboard necessarily is the same for all VT's, so
they ought to all use the same layout. If my "x" is in an
odd place, then it is so for all VT's, if there are "volume control"
buttons, then they exist for all VT's and so on.

In the multiseat case there are several possibly dissimiliar
keyboards, but then they have separate event devices too.


Helge Hafting

[PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN (v2)

[Henrique de Moraes Holschuh]

We have most of the pieces needed to have sane, generic userland keyboard
handling in place for a while now, but it is not sufficiently documented.

This patch documents the requirements and best practices for EV_KEY input
drivers.

Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: Richard Hughes <hughsient@gmail.com>
---

 I have changed the KEY_UNKNOWN preference over positional keycodes around,
 and also added a small paragraph on the expected behaviour of userland
 applications re. EV_MSC MSC_SCAN events.

 Comments?

 Documentation/input/input-programming.txt |   45 ++++++++++++++++++++++++++++-
 1 files changed, 44 insertions(+), 1 deletions(-)

diff --git a/Documentation/input/input-programming.txt b/Documentation/input/input-programming.txt
index d9d5230..30fd051 100644
--- a/Documentation/input/input-programming.txt
+++ b/Documentation/input/input-programming.txt
@@ -272,7 +272,50 @@ present, it is broken sometimes (at keyboards: Toshiba notebooks). To enable
 autorepeat for your device, just set EV_REP in dev->evbit. All will be
 handled by the input system.
 
-1.9 Other event types, handling output events
+1.9 Being friendly to userspace when implementing EV_KEY drivers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Input drivers that generate EV_KEY events should always support either
+dev->getkeycode()/dev->setkeycode(), or keycode, keycodemax and keycodesize,
+so as to allow userspace to reprogram the keycodes as needed.  They should
+also either always generate EV_MSC MSC_SCAN events along with every EV_KEY
+event, or special case EV_KEY KEY_UNKNOWN as described below.
+
+Userspace applications, on the other hand, should never try to remap keys by
+default based solely on EV_MSC MSC_SCAN if that event is part of an event
+block that contains an EV_KEY event other than EV_KEY KEY_UNKNOWN.
+
+If the input driver doesn't support any of the generic methods to manipulate
+the keycode map, it must never issue a EV_KEY KEY_UNKNOWN event.  If you
+need to issue EV_KEY KEY_UNKNOWN events, please implement the code in your
+driver to manipulate its keycode map.  KEY_UNKNOWN is meant to be something
+that can be replaced by the user with a functional keycode.
+
+If the input driver generates an EV_KEY KEY_UNKNOWN event, it should also
+generate *in the same event block* (i.e. before it issues an EV_SYN) an
+EV_MSC MSC_SCAN event, with the scan code for the "unknown key".  This
+should be done both in "press" and "release" EV_KEY events.  The EV_MSC
+MSC_SCAN event allows a generic userspace keyboard helper daemon to ask the
+user if he would like to map a key in a input device to a valid keycode, and
+assign a function to it.
+
+The scan code of a key (as informed in a EV_MSC MSC_SCAN event) must be its
+index in the keycode map, as implemented by dev->getkeycode() /
+dev->setkeycode(), or keycode, keycodemax and keycodesize for the device.
+
+If a key has a specific function that is known to the driver, it should
+generate the appropriate keycode for that function by default.  E.g., in a
+laptop where the FN+F1 key combination is always marked "HELP" in the
+keyboard, the driver is to generate KEY_HELP and not KEY_FN_F1.
+
+If a positional keycode for a key already exists in input.h (e.g. KEY_FN_F1
+for FN+F1), it should be used instead of KEY_UNKNOWN.  When such a code
+doesn't exist or doesn't make any sense for a key, EV_KEY KEY_UNKNOWN is to
+be used.
+
+Non-positional keycodes like KEY_PROG1 should never be used by default.
+
+1.10 Other event types, handling output events
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The other event types up to now are:
-- 
1.5.1.6


-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN (v2)

[Dmitry Torokhov]

Hi Henrique,

On Wednesday 06 June 2007 12:55, Henrique de Moraes Holschuh wrote:
> We have most of the pieces needed to have sane, generic userland keyboard
> handling in place for a while now, but it is not sufficiently documented.
> 
> This patch documents the requirements and best practices for EV_KEY input
> drivers.
> 
> Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
> Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
> Cc: Richard Hughes <hughsient@gmail.com>
> ---
> 
>  I have changed the KEY_UNKNOWN preference over positional keycodes around,
>  and also added a small paragraph on the expected behaviour of userland
>  applications re. EV_MSC MSC_SCAN events.
> 
>  Comments?

Finally gottent to the patch. It seems a little long-winded, how about
the patch below instead?

-- 
Dmitry

Subject: Input: document the proper usage of EV_KEY and KEY_UNKNOWN
From: Henrique de Moraes Holschuh <hmh@hmh.eng.br>


We have most of the pieces needed to have sane, generic userland keyboard
handling in place for a while now, but it is not sufficiently documented.

This patch documents the requirements and best practices for EV_KEY input
drivers.

Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Signed-off-by: Dmitry Torokhov <dtor@mail.ru>
---

 Documentation/input/input-programming.txt |   36 ++++++++++++++++++++++++++++--
 1 files changed, 34 insertions(+), 2 deletions(-)

Index: work/Documentation/input/input-programming.txt
===================================================================
--- work.orig/Documentation/input/input-programming.txt
+++ work/Documentation/input/input-programming.txt
@@ -263,7 +263,38 @@ getkeycode() and setkeycode() callbacks 
 keycode/keycodesize/keycodemax mapping mechanism provided by input core
 and implement sparse keycode maps.
 
-1.8 Key autorepeat
+1.8 Keymaps and KEY_UNKNOWN
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Follow these rules when creating a default keymap for an input device:
+
+- If a key has a specific function that is known to the driver, it should
+  generate keycode corresponding to that function. FOr example, in a laptop
+  where FN+F1 key combination is always marked "HELP" the driver should
+  generate KEY_HELP and not KEY_FN_F1.
+
+- If a positional keycode for a key already exists in input.h (e.g. KEY_FN_F1
+  for FN+F1), it should be used instead of KEY_UNKNOWN. When such a code
+  doesn't exist KEY_UNKNOWN should be used.
+
+- Non-positional keycodes like KEY_PROG1 should be avoided.
+
+Input drivers that generate EV_KEY events should always support either
+dev->getkeycode()/dev->setkeycode(), or keycode, keycodemax and keycodesize
+methods of reprogramming their keymaps. Drivers that do not allow changing
+keycode map should not genrate KEY_UNKNOWN events.
+
+In addition to EV_KEY events drivers should also generate EV_MSC/MSC_SCAN
+events. This event provides assistance to a generic userspace keyboard helper
+in remapping keys and assigning them specific function.
+
+MSC_SCAN event should be sent in the same event block (marked by
+EV_SYN/SYN_REPORT event) as corresponding EV_KEY event. The scan code
+reported must be a valid index in the keycode map, as implemented by
+dev->getkeycode()/dev->setkeycode(), or keycode, keycodemax and keycodesize
+for the device.
+
+1.9 Key autorepeat
 ~~~~~~~~~~~~~~~~~~
 
 ... is simple. It is handled by the input.c module. Hardware autorepeat is
@@ -272,7 +303,8 @@ present, it is broken sometimes (at keyb
 autorepeat for your device, just set EV_REP in dev->evbit. All will be
 handled by the input system.
 
-1.9 Other event types, handling output events
+
+1.10 Other event types, handling output events
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The other event types up to now are:

Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN (v2)

[Henrique de Moraes Holschuh]

On Fri, 29 Jun 2007, Dmitry Torokhov wrote:
> Finally gottent to the patch. It seems a little long-winded, how about
> the patch below instead?

Well, your version of the patch:

1. does not make it clear to *userland* that using EV_SCAN instead of EV_KEY
is something that is not to be done.  If userland wants to use a key that is
not generating an useful EV_KEY, it must remap the key to something.
Otherwise, we are opening our flank to the crap we have with that kludge
from hell AT keyboard reverse scan-code generation all again...  it might
have been unavoidable with the AT keyboard, due to legacy stuff, but there
is no way we should let it happen to anything else.

2. does not make it clear that EV_SCAN events must reflect the scan code
that, when remapped, would reprogram the key that caused that EV_SCAN event
to be generated.

I think these two points need to be addressed by the docs.

-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh