[PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Henrique de Moraes Holschuh]

Add hotkeys available in almost all ThinkPads manufactured in the last five
years (more than one million machines given the ammount of batteries
recalled) to input.h, and make thinkpad-acpi use those instead of issuing
KEY_UNKNOWN.

KEY_FN_PAGEDOWN is not ever reported by the ThinkPad firmware due to random
bogon-induced stupidity at IBM some years ago, but it is provided because
it doesn't make sense to define KEY_FN_PAGEUP and not define
KEY_FN_PAGEDOWN at the same time.

Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Cc: dtor@mail.ru
Cc: linux-input@atrey.karlin.mff.cuni.cz
---
 drivers/misc/thinkpad_acpi.c |    2 +-
 include/linux/input.h        |    5 +++++
 2 files changed, 6 insertions(+), 1 deletions(-)

diff --git a/drivers/misc/thinkpad_acpi.c b/drivers/misc/thinkpad_acpi.c
index 5690247..79a243a 100644
--- a/drivers/misc/thinkpad_acpi.c
+++ b/drivers/misc/thinkpad_acpi.c
@@ -712,7 +712,7 @@ static u16 hotkey_event_map[16] = {
 	KEY_FN_F1, KEY_FN_F2, KEY_FN_F3, KEY_FN_F4, KEY_FN_F5, KEY_FN_F6,
 	KEY_FN_F7, KEY_FN_F8, KEY_FN_F9, KEY_FN_F10, KEY_FN_F11, KEY_FN_F12,
 	/* backspace/ins/del/home */
-	KEY_RESERVED, KEY_RESERVED, KEY_RESERVED, KEY_RESERVED
+	KEY_FN_BACKSPACE, KEY_FN_INSERT, KEY_FN_DELETE, KEY_FN_HOME
 };
 
 static struct attribute_set *hotkey_dev_attributes = NULL;
diff --git a/include/linux/input.h b/include/linux/input.h
index bde65c8..cd0b13e 100644
--- a/include/linux/input.h
+++ b/include/linux/input.h
@@ -533,6 +533,11 @@ struct input_absinfo {
 #define KEY_FN_F		0x1e2
 #define KEY_FN_S		0x1e3
 #define KEY_FN_B		0x1e4
+#define KEY_FN_BACKSPACE	0x1e5
+#define KEY_FN_INSERT		0x1e6
+#define KEY_FN_DELETE		0x1e7
+#define KEY_FN_HOME		0x1e8
+#define KEY_FN_END		0x1e9
 
 #define KEY_BRL_DOT1		0x1f1
 #define KEY_BRL_DOT2		0x1f2
-- 
1.5.1.6

Re: [PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Dmitry Torokhov]

On Saturday 26 May 2007 13:31, Henrique de Moraes Holschuh wrote:
> Add hotkeys available in almost all ThinkPads manufactured in the last five
> years (more than one million machines given the ammount of batteries
> recalled) to input.h, and make thinkpad-acpi use those instead of issuing
> KEY_UNKNOWN.
> 
> KEY_FN_PAGEDOWN is not ever reported by the ThinkPad firmware due to random
> bogon-induced stupidity at IBM some years ago, but it is provided because
> it doesn't make sense to define KEY_FN_PAGEUP and not define
> KEY_FN_PAGEDOWN at the same time.
> 

I am unconvinced that we need new keycodes. Isn't there a better default
keycodes for these keys? You mentioned that fn+f5 controls radio on many
thinkpads, why don't you use KEY_WLAN in your keymap?
 
-- 
Dmitry

Re: [PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Henrique de Moraes Holschuh]

On Sat, 26 May 2007, Dmitry Torokhov wrote:
> On Saturday 26 May 2007 13:31, Henrique de Moraes Holschuh wrote:
> > Add hotkeys available in almost all ThinkPads manufactured in the last five
> > years (more than one million machines given the ammount of batteries
> > recalled) to input.h, and make thinkpad-acpi use those instead of issuing
> > KEY_UNKNOWN.
> > 
> > KEY_FN_PAGEDOWN is not ever reported by the ThinkPad firmware due to random
> > bogon-induced stupidity at IBM some years ago, but it is provided because
> > it doesn't make sense to define KEY_FN_PAGEUP and not define
> > KEY_FN_PAGEDOWN at the same time.
> > 
> 
> I am unconvinced that we need new keycodes. Isn't there a better default
> keycodes for these keys? You mentioned that fn+f5 controls radio on many
> thinkpads, why don't you use KEY_WLAN in your keymap?

No can do the KEY-WLAN thing, sorry.  I *don't* have a way to know, unless I
add a model-specific map table to the kernel, and I have been told by
numerous people to don't even try, unless it is for quirks, etc.

Really, what are we to do with that input.h scancode map?  It *IS* supposed
to be absolute, i.e. one is not supposed to reuse keys in there if the
functionality *or* the generic description is not an exact match.  This is
extremely clear, and it makes complete sense from the point of view of
userland: HAL and others can properly assign functions to all scan codes and
it will be always correct.

But then, it is expensive memory-wise, so it is near the current KEY_MAX,
and people are very, very relutant to add another bit to it.

This is definately a ridiculous and aggravating situation, that deserves a
proper fix.  If increasing the scancode table cannot be done (why?), it is
time to stop denying reality, and remove everything after KEY_FN (0x1d0),
and instead give us a block of KEY_HOSTSPECIFIC_* scancodes, from 0x1d0 to
at least 0x1ef.

Given the way that scancode table is being used, it is one way or the other.
Either increase it to KEY_MAX=0x3ff, or do exactly what UNICODE did, give us
a decently sized block of host-specific scancodes, and shunt the problem to
userspace to clean up after.

-- 
  "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] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Henrique de Moraes Holschuh]

On Sun, 27 May 2007, Henrique de Moraes Holschuh wrote:
> On Sat, 26 May 2007, Dmitry Torokhov wrote:
> > On Saturday 26 May 2007 13:31, Henrique de Moraes Holschuh wrote:
> > > Add hotkeys available in almost all ThinkPads manufactured in the last five
> > > years (more than one million machines given the ammount of batteries
> > > recalled) to input.h, and make thinkpad-acpi use those instead of issuing
> > > KEY_UNKNOWN.
> > > 
> > > KEY_FN_PAGEDOWN is not ever reported by the ThinkPad firmware due to random
> > > bogon-induced stupidity at IBM some years ago, but it is provided because
> > > it doesn't make sense to define KEY_FN_PAGEUP and not define
> > > KEY_FN_PAGEDOWN at the same time.
> > > 
> > 
> > I am unconvinced that we need new keycodes. Isn't there a better default
> > keycodes for these keys? You mentioned that fn+f5 controls radio on many
> > thinkpads, why don't you use KEY_WLAN in your keymap?
> 
> No can do the KEY-WLAN thing, sorry.  I *don't* have a way to know, unless I
> add a model-specific map table to the kernel, and I have been told by
> numerous people to don't even try, unless it is for quirks, etc.
> 
> Really, what are we to do with that input.h scancode map?  It *IS* supposed
> to be absolute, i.e. one is not supposed to reuse keys in there if the
> functionality *or* the generic description is not an exact match.  This is
> extremely clear, and it makes complete sense from the point of view of
> userland: HAL and others can properly assign functions to all scan codes and
> it will be always correct.
> 
> But then, it is expensive memory-wise, so it is near the current KEY_MAX,
> and people are very, very relutant to add another bit to it.
> 
> This is definately a ridiculous and aggravating situation, that deserves a
> proper fix.  If increasing the scancode table cannot be done (why?), it is
> time to stop denying reality, and remove everything after KEY_FN (0x1d0),
> and instead give us a block of KEY_HOSTSPECIFIC_* scancodes, from 0x1d0 to
> at least 0x1ef.
> 
> Given the way that scancode table is being used, it is one way or the other.
> Either increase it to KEY_MAX=0x3ff, or do exactly what UNICODE did, give us
> a decently sized block of host-specific scancodes, and shunt the problem to
> userspace to clean up after.

I can come up with a patch that converts all the keycodes after KEY_FN to
host-specific keycodes, and fix all in-tree drivers to use them (without
modifying any of the scancodes they will generate, i.e. maintaining the ABI
to userspace).  Is there any chance of such a patch being accepted?
Otherwise, I'd rather waste my time doing something else :-)

-- 
  "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] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Dmitry Torokhov]

On Sunday 27 May 2007 08:15, Henrique de Moraes Holschuh wrote:
> On Sat, 26 May 2007, Dmitry Torokhov wrote:
> > On Saturday 26 May 2007 13:31, Henrique de Moraes Holschuh wrote:
> > > Add hotkeys available in almost all ThinkPads manufactured in the last five
> > > years (more than one million machines given the ammount of batteries
> > > recalled) to input.h, and make thinkpad-acpi use those instead of issuing
> > > KEY_UNKNOWN.
> > > 
> > > KEY_FN_PAGEDOWN is not ever reported by the ThinkPad firmware due to random
> > > bogon-induced stupidity at IBM some years ago, but it is provided because
> > > it doesn't make sense to define KEY_FN_PAGEUP and not define
> > > KEY_FN_PAGEDOWN at the same time.
> > > 
> > 
> > I am unconvinced that we need new keycodes. Isn't there a better default
> > keycodes for these keys? You mentioned that fn+f5 controls radio on many
> > thinkpads, why don't you use KEY_WLAN in your keymap?
> 
> No can do the KEY-WLAN thing, sorry.  I *don't* have a way to know, unless I
> add a model-specific map table to the kernel, and I have been told by
> numerous people to don't even try, unless it is for quirks, etc.
> 

Why not? It thinkpad-acpi is a box-specific driver and you could try to
setup proper keymap depending on models. We do that in wistron_btns and
it doers not even need alot of memory (keymaps and dmi data is marked
__initdata and is discarded).

> Really, what are we to do with that input.h scancode map?  It *IS* supposed
> to be absolute, i.e. one is not supposed to reuse keys in there if the
> functionality *or* the generic description is not an exact match.

Are there any markings on those keys?

> This is 
> extremely clear, and it makes complete sense from the point of view of
> userland: HAL and others can properly assign functions to all scan codes and
> it will be always correct.
>

Are you arguing for KEY_THINKPAD_FN_F1, etc? And it being different from
KEY_ACER_FN_F1? I don't think it is a good idea... 
 
> But then, it is expensive memory-wise, so it is near the current KEY_MAX,
> and people are very, very relutant to add another bit to it.
>

Not really expensive. Right now keys cost 128 bytes per input device,
absolute axis data cost much more. If we really need it we could increase
KEY_MAX.
 
> This is definately a ridiculous and aggravating situation, that deserves a
> proper fix.  If increasing the scancode table cannot be done (why?), it is
> time to stop denying reality, and remove everything after KEY_FN (0x1d0),
> and instead give us a block of KEY_HOSTSPECIFIC_* scancodes, from 0x1d0 to
> at least 0x1ef.
> 
> Given the way that scancode table is being used, it is one way or the other.
> Either increase it to KEY_MAX=0x3ff, or do exactly what UNICODE did, give us
> a decently sized block of host-specific scancodes, and shunt the problem to
> userspace to clean up after.
>

In this case I better do nothing and leave everything as KEY_RESERVED and
let userspace load proper keymap for the device.  

-- 
Dmitry

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/

Re: [PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Henrique de Moraes Holschuh]

On Mon, 28 May 2007, Dmitry Torokhov wrote:
> On Sunday 27 May 2007 08:15, Henrique de Moraes Holschuh wrote:
> > On Sat, 26 May 2007, Dmitry Torokhov wrote:
> > > I am unconvinced that we need new keycodes. Isn't there a better default
> > > keycodes for these keys? You mentioned that fn+f5 controls radio on many
> > > thinkpads, why don't you use KEY_WLAN in your keymap?
> > 
> > No can do the KEY-WLAN thing, sorry.  I *don't* have a way to know, unless I
> > add a model-specific map table to the kernel, and I have been told by
> > numerous people to don't even try, unless it is for quirks, etc.
> 
> Why not? It thinkpad-acpi is a box-specific driver and you could try to
> setup proper keymap depending on models. We do that in wistron_btns and
> it doers not even need alot of memory (keymaps and dmi data is marked
> __initdata and is discarded).

Well, I will try, let's see if ACPI upstream will take it after I tell them
it was decided to be the best approach by the input layer people.  Yes, it
can be __initdata, so it should not cause any drawbacks.

But I will still need to add keys, and I still think that a bunch of 32 or
so HOSTSPECIFIC keys is a very very good idea to have, *even* if I add some
model specific knowledge and already remap a few of the hot key keyboard to
less generic events where possible.

> > Really, what are we to do with that input.h scancode map?  It *IS* supposed
> > to be absolute, i.e. one is not supposed to reuse keys in there if the
> > functionality *or* the generic description is not an exact match.
> 
> Are there any markings on those keys?

Only a few of them.  And the ones I wanted to add are *not* marked in most
models :-)

The markings change a bit from model to model, and we have a *very*
incomplete list of those...

> > This is 
> > extremely clear, and it makes complete sense from the point of view of
> > userland: HAL and others can properly assign functions to all scan codes and
> > it will be always correct.
> 
> Are you arguing for KEY_THINKPAD_FN_F1, etc? And it being different from
> KEY_ACER_FN_F1? I don't think it is a good idea... 

No.  I am arguing for

#define KEY_HOSTSPECIFIC_01  0x1d0
...
#define KEY_HOSTSPECIFIC_32  0x1ef

And using that in place of KEY_FN, KEY_FN_F1... etc.  Userspace will be
responsible for mapping THESE keys (and only these keys) to something that
makes sense.  But I am arguing for this if, and only if, we cannot extend
KEY_MAX.

Alternatively, if you let me add keys, I will need a few of them, and they
are also generic (not necessarily thinkpad-specific).  Stuff like:

KEY_FN_BACKSPACE,
KEY_VENDORHOMEPAGE,
etc.

This will nearly exaust, or it might even exaust the current KEY_MAX space,
and KEY_MAX will need to get bumped one extra bit.  I still think *this* is
the best solution, but I offered the KEY_HOSTSPECIFIC one because I
perceived a big resistence to adding new keys and increasing KEY_MAX in the
past...

> > But then, it is expensive memory-wise, so it is near the current KEY_MAX,
> > and people are very, very relutant to add another bit to it.
> 
> Not really expensive. Right now keys cost 128 bytes per input device,
> absolute axis data cost much more. If we really need it we could increase
> KEY_MAX.

Well, I would *really* appreciate if I can add the thinkpad hot keys to the
key map, then.  It is best for userspace, and it keeps the scan code
generation style we have been using for a long time, where you assign keys
every time there is not a match that serves *exactly*.

I know I am in the unconfortable position of being the poor schmuck that had
to ask for it when the perceived cost is bigger (i.e. I will need, maybe one
or two keys in the 0x200 range, if any at all), but someone had to be it.

> > This is definately a ridiculous and aggravating situation, that deserves a
> > proper fix.  If increasing the scancode table cannot be done (why?), it is
> > time to stop denying reality, and remove everything after KEY_FN (0x1d0),
> > and instead give us a block of KEY_HOSTSPECIFIC_* scancodes, from 0x1d0 to
> > at least 0x1ef.
> > 
> > Given the way that scancode table is being used, it is one way or the other.
> > Either increase it to KEY_MAX=0x3ff, or do exactly what UNICODE did, give us
> > a decently sized block of host-specific scancodes, and shunt the problem to
> > userspace to clean up after.
> 
> In this case I better do nothing and leave everything as KEY_RESERVED and
> let userspace load proper keymap for the device.

That is a really, really undesireable solution.  It is worse than
KEY_HOSTSPECIFIC, and much worse than increasing KEY_MAX.  Can't we go with
one of the other two?  Either one would give a sound technical solution to
the issue.

Papering over the problem won't make it go away, after all.

-- 
  "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

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/

Re: [PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Dmitry Torokhov]

On 5/29/07, Henrique de Moraes Holschuh <hmh@hmh.eng.br> wrote:
> On Mon, 28 May 2007, Dmitry Torokhov wrote:
> > On Sunday 27 May 2007 08:15, Henrique de Moraes Holschuh wrote:
> > > On Sat, 26 May 2007, Dmitry Torokhov wrote:
> > > > I am unconvinced that we need new keycodes. Isn't there a better default
> > > > keycodes for these keys? You mentioned that fn+f5 controls radio on many
> > > > thinkpads, why don't you use KEY_WLAN in your keymap?
> > >
> > > No can do the KEY-WLAN thing, sorry.  I *don't* have a way to know, unless I
> > > add a model-specific map table to the kernel, and I have been told by
> > > numerous people to don't even try, unless it is for quirks, etc.
> >
> > Why not? It thinkpad-acpi is a box-specific driver and you could try to
> > setup proper keymap depending on models. We do that in wistron_btns and
> > it doers not even need alot of memory (keymaps and dmi data is marked
> > __initdata and is discarded).
>
> Well, I will try, let's see if ACPI upstream will take it after I tell them
> it was decided to be the best approach by the input layer people.  Yes, it
> can be __initdata, so it should not cause any drawbacks.
>
> But I will still need to add keys, and I still think that a bunch of 32 or
> so HOSTSPECIFIC keys is a very very good idea to have, *even* if I add some
> model specific knowledge and already remap a few of the hot key keyboard to
> less generic events where possible.
>

I think that adding anything like HOSTSPECIFIC is a failure on our
part. That means that you need to make programs out there aware of
multiple hosts and their usage. You can't just say that you going to
teach X and the rest will use X facilities because there is world
outside of X. Programs like HAL, network management (rfkill) other
daemons getting input directly from /dev/input/eventX will have to be
made aware. This is not good.

I really don't like KEY_FN_F1..KEY_FN_BACKSPACE either. What are they
supposed to do? Just being an unique value to be mapped onto something
useful? But why not use that useful keycode to begin with?

I'd rather leave the keys unmapped and rely on initsripts (possibly
with help from distributions vendors) to load proper keymap then add
something that must be retranslated over and over again.

> > > Really, what are we to do with that input.h scancode map?  It *IS* supposed
> > > to be absolute, i.e. one is not supposed to reuse keys in there if the
> > > functionality *or* the generic description is not an exact match.
> >
> > Are there any markings on those keys?
>
> Only a few of them.  And the ones I wanted to add are *not* marked in most
> models :-)
>
> The markings change a bit from model to model, and we have a *very*
> incomplete list of those...
>

Well, what kind of functions you would like them to have? You, as a
maintainer, can chose defaults. Since you (well, not you, the driver)
provide a way for a user to adjust keymap there should be no problem
even if someone does not like the values you chose. Having sensible
defaults is a good thing, otherwise many people will not even know
that they have these "separate" keys.

>
> Alternatively, if you let me add keys, I will need a few of them, and they
> are also generic (not necessarily thinkpad-specific).  Stuff like:
>
> KEY_FN_BACKSPACE,
> KEY_VENDORHOMEPAGE,

And what are their intended functions would be? How KEY_VENDORHOMEPAGE
is different from KEY_HOMEPAGE?

-- 
Dmitry

Re: [PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Matthew Garrett]

On Wed, May 30, 2007 at 09:57:11AM -0400, Dmitry Torokhov wrote:

> I really don't like KEY_FN_F1..KEY_FN_BACKSPACE either. What are they
> supposed to do? Just being an unique value to be mapped onto something
> useful? But why not use that useful keycode to begin with?

We've already got KEY_PROG* - is this not the sort of situation they're 
for? (ie, keys that aren't mapped to a specific purpose but would be 
potentially useful to userspace at the per-user level)

> I'd rather leave the keys unmapped and rely on initsripts (possibly
> with help from distributions vendors) to load proper keymap then add
> something that must be retranslated over and over again.

Changing the keymap is a privileged operation, so sending /some/ sort of 
keycode by default would probably be good.

> Well, what kind of functions you would like them to have? You, as a
> maintainer, can chose defaults. Since you (well, not you, the driver)
> provide a way for a user to adjust keymap there should be no problem
> even if someone does not like the values you chose. Having sensible
> defaults is a good thing, otherwise many people will not even know
> that they have these "separate" keys.

Some of the Thinkpad keys send events even without there being any 
label, so I don't think there's a sane default other than leaving it up 
to the user. On the other hand, I'm not especially keen on sending 
literals like "FN_BACKSPACE" - it's hugely special-cased.

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

Re: [PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Dmitry Torokhov]

Hi Matthew,

On 5/30/07, Matthew Garrett <mjg59@srcf.ucam.org> wrote:
> On Wed, May 30, 2007 at 09:57:11AM -0400, Dmitry Torokhov wrote:
>
> > I really don't like KEY_FN_F1..KEY_FN_BACKSPACE either. What are they
> > supposed to do? Just being an unique value to be mapped onto something
> > useful? But why not use that useful keycode to begin with?
>
> We've already got KEY_PROG* - is this not the sort of situation they're
> for? (ie, keys that aren't mapped to a specific purpose but would be
> potentially useful to userspace at the per-user level)
>

Right. These are they keys "we have no idea how to use these, leave it
to the user". Do we really need more of these? We have quite a few
codes that might be useful. I just don't want to keep adding a new
input keycode every time we encounter an unmarked key somewhere.

> > I'd rather leave the keys unmapped and rely on initsripts (possibly
> > with help from distributions vendors) to load proper keymap then add
> > something that must be retranslated over and over again.
>
> Changing the keymap is a privileged operation, so sending /some/ sort of
> keycode by default would probably be good.
>

It's up to the security policy on a particular box. One could change
/dev/input/evdev ownership to the user currently logged on physical
console.

Overall I think adjusting the keymap at boot time (so per-installation
case) will cover most of users.

> > Well, what kind of functions you would like them to have? You, as a
> > maintainer, can chose defaults. Since you (well, not you, the driver)
> > provide a way for a user to adjust keymap there should be no problem
> > even if someone does not like the values you chose. Having sensible
> > defaults is a good thing, otherwise many people will not even know
> > that they have these "separate" keys.
>
> Some of the Thinkpad keys send events even without there being any
> label, so I don't think there's a sane default other than leaving it up
> to the user. On the other hand, I'm not especially keen on sending
> literals like "FN_BACKSPACE" - it's hugely special-cased.
>

That's why maintainer gets to chose his favorite keymap (from
available keycodes ;) ) and anyone who's unhappy with the coise gets
to add couple of lines in rc.local.

Also there is DMI and possibility to  load install different keymaps
this way (which Ithink is good for vendor-specific drivers - I woudl
not add dmi to atkbd for example because you never know what external
keyboard user may plug in).

-- 
Dmitry

Re: [PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Matthew Garrett]

On Wed, May 30, 2007 at 10:18:17AM -0400, Dmitry Torokhov wrote:
> Hi Matthew,
> >We've already got KEY_PROG* - is this not the sort of situation they're
> >for? (ie, keys that aren't mapped to a specific purpose but would be
> >potentially useful to userspace at the per-user level)
> >
> 
> Right. These are they keys "we have no idea how to use these, leave it
> to the user". Do we really need more of these? We have quite a few
> codes that might be useful. I just don't want to keep adding a new
> input keycode every time we encounter an unmarked key somewhere.

Sorry, I wasn't clear - I was thinking that they should just be used for 
this case, rather than that more of them be added.

> >Changing the keymap is a privileged operation, so sending /some/ sort of
> >keycode by default would probably be good.
> >
> 
> It's up to the security policy on a particular box. One could change
> /dev/input/evdev ownership to the user currently logged on physical
> console.

Most users will be logged into X, so it's the X keymap that's the most 
interesting one. X tools know how to remap the X keymap without 
requiring any sort of special privileges, so all we need is for the 
keycode to generate /something/. I think KEY_PROG* would make the most 
sense, and that's what we've adopted in Ubuntu.

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

Re: [PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Dmitry Torokhov]

On 5/30/07, Matthew Garrett <mjg59@srcf.ucam.org> wrote:
> On Wed, May 30, 2007 at 10:18:17AM -0400, Dmitry Torokhov wrote:
> > Hi Matthew,
> > >We've already got KEY_PROG* - is this not the sort of situation they're
> > >for? (ie, keys that aren't mapped to a specific purpose but would be
> > >potentially useful to userspace at the per-user level)
> > >
> >
> > Right. These are they keys "we have no idea how to use these, leave it
> > to the user". Do we really need more of these? We have quite a few
> > codes that might be useful. I just don't want to keep adding a new
> > input keycode every time we encounter an unmarked key somewhere.
>
> Sorry, I wasn't clear - I was thinking that they should just be used for
> this case, rather than that more of them be added.
>

Ah, OK.

> > >Changing the keymap is a privileged operation, so sending /some/ sort of
> > >keycode by default would probably be good.
> > >
> >
> > It's up to the security policy on a particular box. One could change
> > /dev/input/evdev ownership to the user currently logged on physical
> > console.
>
> Most users will be logged into X, so it's the X keymap that's the most
> interesting one. X tools know how to remap the X keymap without
> requiring any sort of special privileges, so all we need is for the
> keycode to generate /something/. I think KEY_PROG* would make the most
> sense, and that's what we've adopted in Ubuntu.

Not all world is X :)  Actually few of "FN" keys, like KEY_WLAN,
KEY_SLEEP, etc should be handled not [only] by X but by other layers.

-- 
Dmitry

Re: [PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Matthew Garrett]

On Wed, May 30, 2007 at 10:31:35AM -0400, Dmitry Torokhov wrote:

> Not all world is X :)  Actually few of "FN" keys, like KEY_WLAN,
> KEY_SLEEP, etc should be handled not [only] by X but by other layers.

I agree - the ones that have a defined function should certainly be set 
to sensible defaults, but I think the sensible default for a key without 
a defined function is "Key of undefined function" (like KEY_PROG*), not 
"Key which doesn't generate a keycode" :)

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

Re: [PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Henrique de Moraes Holschuh]

On Wed, 30 May 2007, Dmitry Torokhov wrote:
> On 5/30/07, Matthew Garrett <mjg59@srcf.ucam.org> wrote:
> >We've already got KEY_PROG* - is this not the sort of situation they're
> >for? (ie, keys that aren't mapped to a specific purpose but would be
> >potentially useful to userspace at the per-user level)
> 
> Right. These are they keys "we have no idea how to use these, leave it
> to the user". Do we really need more of these? We have quite a few

Drat, I didn't know of those, otherwise I would not have asked for
KEY_HOSTSPECIFIC_*.  Thanks for the hint, Matthew!

But there are too few KEY_PROG symbols.  I'd need more than four of them for
the entire set of thinkpad hot keys (including nvram-based ones).

> codes that might be useful. I just don't want to keep adding a new
> input keycode every time we encounter an unmarked key somewhere.

A big enough set of KEY_PROG* would fix this.  It is basically my argument
for KEY_HOSTSPECIFIC, only that it has a different name, and that we already
have four of them.

> >> Well, what kind of functions you would like them to have? You, as a
> >> maintainer, can chose defaults. Since you (well, not you, the driver)
> >> provide a way for a user to adjust keymap there should be no problem
> >> even if someone does not like the values you chose. Having sensible
> >> defaults is a good thing, otherwise many people will not even know
> >> that they have these "separate" keys.
> >
> >Some of the Thinkpad keys send events even without there being any
> >label, so I don't think there's a sane default other than leaving it up
> >to the user. On the other hand, I'm not especially keen on sending
> >literals like "FN_BACKSPACE" - it's hugely special-cased.

Well, I'd like to have a keycode I could use so that I have it working
out-of-the-box.  It can be KEY_PROG*, if there are enough of them (can I add
more?).   Or it will be something with a specific function, when I know what
the marking on the key is.

But really, not sending a keycode at all is non-optimal.  And using a
keycode that should be for something else (say, KEY_F13) is just wrong.

-- 
  "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] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Henrique de Moraes Holschuh]

On Wed, 30 May 2007, Dmitry Torokhov wrote:
> On 5/29/07, Henrique de Moraes Holschuh <hmh@hmh.eng.br> wrote:
> >But I will still need to add keys, and I still think that a bunch of 32 or
> >so HOSTSPECIFIC keys is a very very good idea to have, *even* if I add some
> >model specific knowledge and already remap a few of the hot key keyboard to
> >less generic events where possible.
> 
> I think that adding anything like HOSTSPECIFIC is a failure on our
> part. That means that you need to make programs out there aware of

Well, you have to choose one of three possibilities for an unlabelled key:

1. Generate SOMETHING that has an undefined meaning or function, but which
is unique for that keyboard (KEY_PROG/KEY_HOSTSPECIFIC)

2. Generate SOMETHING that has a non-specific function, but a well defined
meaning (KEY_FN_F1)

3. Do nothing.

I *REALLY* do not like (3), and so far I have not seen a single good
technical reason to go with it.  From the technically sound ones, you need
to either have the keycodes you need for (2) (i.e. KEY_FN_BACKSPACE), or a
big enough set of keycodes to use (1) (i.e. KEY_PROG5..KEY_PROGn, where n
should probably be at least 8).

> I really don't like KEY_FN_F1..KEY_FN_BACKSPACE either. What are they
> supposed to do? Just being an unique value to be mapped onto something
> useful? But why not use that useful keycode to begin with?

Yes, just an unique value to be mapped onto something useful, by something
in userspace.  Just like KEY_PROG, actually.

One can't use a "useful keycode" for two reasons:

1.	Because the key has no set function (it is unmarked)
2.	Because it has, or could have, a set function, but we have no clue
which is it.

> I'd rather leave the keys unmapped and rely on initsripts (possibly
> with help from distributions vendors) to load proper keymap then add
> something that must be retranslated over and over again.

I don't.  I can live with it, of course, but if we are going to go that way,
what IS the excuse for a big lot of the keys already in input.h?  We have
been adding the unique keycodes and functional keycodes because it is
*useful*.

Again, let me remind you that I have nothing against using functional
keycodes (KEY_HOMEPAGE, KEY_WLAN) when we know the key is actually that, and
that all I am asking for is some non-wrong keycode to use when we don't (so
that I don't use KEY_F13 for KEY_FN_INSERT, for example).

Heck, I even proposed to write a patch to do away with most of the KEY_FN
and make them into KEY_HOSTSPECIFIC (now it would be KEY_PROG, of course),
which would stop wasting keymap codepoints for stuff that has no set
functions, anyway.

Of course, if I needed keys for a specific function, I'd be asking for them
instead, but I am not there yet.

> And what are their intended functions would be? How KEY_VENDORHOMEPAGE
> is different from KEY_HOMEPAGE?

KEY_VENDORHOMEPAGE is exactly that.  It is marked with the vendor's name.
KEY_HOMEPAGE has a defined function inherited from that other O.S. which is
to open up the default browser on the default "homepage".  I can easily see
both keys existing on a system.

As for stuff like KEY_FN_BACKSPACE, well, I don't really care, as long as I
have *something* unique and not incorrect to use.  But if we are not going
to add extra KEY_FN_ keycodes, why don't we just convert them all to
KEY_PROG, so that they can be useful to all and not just to people who have
FN_<whatever> keys?

-- 
  "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] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Dmitry Torokhov]

On 5/30/07, Henrique de Moraes Holschuh <hmh@hmh.eng.br> wrote:
> On Wed, 30 May 2007, Dmitry Torokhov wrote:
> > On 5/29/07, Henrique de Moraes Holschuh <hmh@hmh.eng.br> wrote:
> > >But I will still need to add keys, and I still think that a bunch of 32 or
> > >so HOSTSPECIFIC keys is a very very good idea to have, *even* if I add some
> > >model specific knowledge and already remap a few of the hot key keyboard to
> > >less generic events where possible.
> >
> > I think that adding anything like HOSTSPECIFIC is a failure on our
> > part. That means that you need to make programs out there aware of
>
> Well, you have to choose one of three possibilities for an unlabelled key:
>
> 1. Generate SOMETHING that has an undefined meaning or function, but which
> is unique for that keyboard (KEY_PROG/KEY_HOSTSPECIFIC)
>

How do you guarantee that KEY_PROG* is unique for the keyboard? What
do you do if you have 2 devices generating KEY_PROG1?

> 2. Generate SOMETHING that has a non-specific function, but a well defined
> meaning (KEY_FN_F1)

And we have plenty of those.

>
> 3. Do nothing.
>

Well, probably not nothing. Map it to KEY_UNKNOWN and have userspace
listen to such events and inform user when it presses such a key that
such and such happened and tell him how to map it to something useful.

> I *REALLY* do not like (3), and so far I have not seen a single good
> technical reason to go with it.

Reasons: do not require expaning current keymap preserving space for
more useful keycodes.

>  From the technically sound ones, you need
> to either have the keycodes you need for (2) (i.e. KEY_FN_BACKSPACE), or a
> big enough set of keycodes to use (1) (i.e. KEY_PROG5..KEY_PROGn, where n
> should probably be at least 8).

Why 8? Why not 16? Or 32 just to make sure?

>
> > I really don't like KEY_FN_F1..KEY_FN_BACKSPACE either. What are they
> > supposed to do? Just being an unique value to be mapped onto something
> > useful? But why not use that useful keycode to begin with?
>
> Yes, just an unique value to be mapped onto something useful, by something
> in userspace.  Just like KEY_PROG, actually.
>

In _every_ program that gets events directly?

> One can't use a "useful keycode" for two reasons:
>
> 1.      Because the key has no set function (it is unmarked)
> 2.      Because it has, or could have, a set function, but we have no clue
> which is it.
>

KEY_UNKNOWN then.

> > I'd rather leave the keys unmapped and rely on initsripts (possibly
> > with help from distributions vendors) to load proper keymap then add
> > something that must be retranslated over and over again.
>
> I don't.  I can live with it, of course, but if we are going to go that way,
> what IS the excuse for a big lot of the keys already in input.h?  We have
> been adding the unique keycodes and functional keycodes because it is
> *useful*.
>

Because they most of them describe an expected _action_ that would
happend after keypress.

[...skipped...]
>
> > And what are their intended functions would be? How KEY_VENDORHOMEPAGE
> > is different from KEY_HOMEPAGE?
>
> KEY_VENDORHOMEPAGE is exactly that.  It is marked with the vendor's name.
> KEY_HOMEPAGE has a defined function inherited from that other O.S. which is
> to open up the default browser on the default "homepage".  I can easily see
> both keys existing on a system.
>

OK, right now we have:

KEY_WWW
KEY_VENDOR
KEY_HOMEPAGE

defines in input.h. Are you sayign that none of these would suit?

> As for stuff like KEY_FN_BACKSPACE, well, I don't really care, as long as I
> have *something* unique and not incorrect to use.  But if we are not going
> to add extra KEY_FN_ keycodes, why don't we just convert them all to
> KEY_PROG, so that they can be useful to all and not just to people who have
> FN_<whatever> keys?
>

We could add aliases if you really want...

Can you tell me on _your_ thinkpad what markings you have? I mean
there should be a common pattern on thinkpads and the rest may be
guessed (you mentioned that FN-F5 is used to turn off radio quite
often so if thinkpad driver detects radio switch it makes sence to
just go ahead and mark FN-F5 as KEY_WLAN, doesn't it?)

-- 
Dmitry

Re: [PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Henrique de Moraes Holschuh]

On Wed, 30 May 2007, Dmitry Torokhov wrote:
> >1. Generate SOMETHING that has an undefined meaning or function, but which
> >is unique for that keyboard (KEY_PROG/KEY_HOSTSPECIFIC)
> 
> How do you guarantee that KEY_PROG* is unique for the keyboard? What
> do you do if you have 2 devices generating KEY_PROG1?

It is trivial to guarantee that KEY_PROG is unique for a single input device
(keyboard), but it certainly won't work across multiple devices.  Userspace
has to know what kind of input device it is talking to to map them to
something, but since the input layer already provides this information, I
was not going to raise a fuss about it.  I figure it is the price of not
increasing even more the keycode table.

> >2. Generate SOMETHING that has a non-specific function, but a well defined
> >meaning (KEY_FN_F1)
> 
> And we have plenty of those.

Yeah, but not enough of them or I would not have asked for five more :-)

> >3. Do nothing.
> 
> Well, probably not nothing. Map it to KEY_UNKNOWN and have userspace
> listen to such events and inform user when it presses such a key that
> such and such happened and tell him how to map it to something useful.

Not optimal, but certainly much better than "do nothing".  I will go with
this one, if I can't have my extra FN keys or PROG keys.

That said, how is one to know which hardware key was translated to
KEY_UNKNOWN, so that he can inform the user to remap that key?  Should I
send another event together with KEY_UNKNOWN that has the raw keycode? Which
one?

> >I *REALLY* do not like (3), and so far I have not seen a single good
> >technical reason to go with it.
> 
> Reasons: do not require expaning current keymap preserving space for
> more useful keycodes.

We should either reclaim space then (remove all of KEY_FN_* and make them
KEY_PROG* generic stuff), or double the entire keycode space (add one bit to
KEY_MAX) so that new keycodes can be added for a while.  Declaring a keycode
crunch on drivers when one gets close to exausting each bit of KEY_MAX is
not a solution IMHO.

> > From the technically sound ones, you need
> >to either have the keycodes you need for (2) (i.e. KEY_FN_BACKSPACE), or a
> >big enough set of keycodes to use (1) (i.e. KEY_PROG5..KEY_PROGn, where n
> >should probably be at least 8).
> 
> Why 8? Why not 16? Or 32 just to make sure?

Eight is a bare minimum (and enough for my needs if the KEY_FN already there
don't go away :p), but I already told you that if it were up to me, I'd
convert all of FN_ to such codes, and cover 0x1d0 to 0x1ef with them, which
gives us 32 generic codes.  We would have 36 KEY_PROG then, which hopefully
would be enough for a while.

> >> I really don't like KEY_FN_F1..KEY_FN_BACKSPACE either. What are they
> >> supposed to do? Just being an unique value to be mapped onto something
> >> useful? But why not use that useful keycode to begin with?
> >
> >Yes, just an unique value to be mapped onto something useful, by something
> >in userspace.  Just like KEY_PROG, actually.
> 
> In _every_ program that gets events directly?

Yes.  It is not nearly as nice as functional key codes (like KEY_WLAN), but
it is better than KEY_UNKONWN or wrong keys.   Of course, if you *know* a
key's function, you use that.

> >One can't use a "useful keycode" for two reasons:
> >
> >1.      Because the key has no set function (it is unmarked)
> >2.      Because it has, or could have, a set function, but we have no clue
> >which is it.
> 
> KEY_UNKNOWN then.

KEY_UNKNOWN requires that userspace remap it for it to be usable.

> >> I'd rather leave the keys unmapped and rely on initsripts (possibly
> >> with help from distributions vendors) to load proper keymap then add
> >> something that must be retranslated over and over again.
> >
> >I don't.  I can live with it, of course, but if we are going to go that 
> >way,
> >what IS the excuse for a big lot of the keys already in input.h?  We have
> >been adding the unique keycodes and functional keycodes because it is
> >*useful*.
> 
> Because they most of them describe an expected _action_ that would
> happend after keypress.

But why can't we get those that do NOT do that and are not around most
keyboards to be completely generic, then?

> [...skipped...]
> >
> >> And what are their intended functions would be? How KEY_VENDORHOMEPAGE
> >> is different from KEY_HOMEPAGE?
> >
> >KEY_VENDORHOMEPAGE is exactly that.  It is marked with the vendor's name.
> >KEY_HOMEPAGE has a defined function inherited from that other O.S. which is
> >to open up the default browser on the default "homepage".  I can easily see
> >both keys existing on a system.
> >
> 
> OK, right now we have:
> 
> KEY_WWW
> KEY_VENDOR
> KEY_HOMEPAGE
> 
> defines in input.h. Are you sayign that none of these would suit?

KEY_VENDOR would work for me.  I had not searched around for one yet, and I
would have found it out before sending you a patch asking for
KEY_VENDORHOMEPAGE.

KEY_PROG, on the other hand, looked to me like an function (like program
macro or whatever).

> >As for stuff like KEY_FN_BACKSPACE, well, I don't really care, as long as I
> >have *something* unique and not incorrect to use.  But if we are not going
> >to add extra KEY_FN_ keycodes, why don't we just convert them all to
> >KEY_PROG, so that they can be useful to all and not just to people who have
> >FN_<whatever> keys?
> 
> We could add aliases if you really want...

If you add aliases to the whole FN block, and add a few more KEY_PROG to
fill the holes so that the entire 0x1d0-0x1ef range is usable by
thinkpad-acpi, that would be enough for me.  I am not sure how that is any
better (or any worse) than the other possible solutions that change input.h,
though.

> Can you tell me on _your_ thinkpad what markings you have? I mean

http://www.thinkwiki.org/wiki/Default_meanings_of_special_keys

Mine is a T43.  That table is not 100% correct, the T43 doesn't label the
fn+f8 or fn+f9 keys.  And it is still very very much incomplete.

> there should be a common pattern on thinkpads and the rest may be
> guessed (you mentioned that FN-F5 is used to turn off radio quite
> often so if thinkpad driver detects radio switch it makes sence to
> just go ahead and mark FN-F5 as KEY_WLAN, doesn't it?)

For that particular key, yes... until we find out a thinkpad that has that
key elsewhere.

-- 
  "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] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Dmitry Torokhov]

On 5/30/07, Henrique de Moraes Holschuh <hmh@hmh.eng.br> wrote:
> On Wed, 30 May 2007, Dmitry Torokhov wrote:
> > >1. Generate SOMETHING that has an undefined meaning or function, but which
> > >is unique for that keyboard (KEY_PROG/KEY_HOSTSPECIFIC)
> >
> > How do you guarantee that KEY_PROG* is unique for the keyboard? What
> > do you do if you have 2 devices generating KEY_PROG1?
>
> It is trivial to guarantee that KEY_PROG is unique for a single input device
> (keyboard), but it certainly won't work across multiple devices.  Userspace
> has to know what kind of input device it is talking to to map them to
> something, but since the input layer already provides this information, I
> was not going to raise a fuss about it.  I figure it is the price of not
> increasing even more the keycode table.
>

Actually I try to discourage people from using input_id during device
discovery but rather tell them to analyze capability bits and then
decide if their application is interested in that particular input
device. I think input_id should pretty much only used by udev & co. to
adjust default kernel setup for the needs of local installation (fix
keymap, adjust absmax, etc).

Applications should focus their attention on functional aspect of the
device. That's why I don't like KEY_PROG* and KEY_FN*.

> > >2. Generate SOMETHING that has a non-specific function, but a well defined
> > >meaning (KEY_FN_F1)
> >
> > And we have plenty of those.
>
> Yeah, but not enough of them or I would not have asked for five more :-)

You already have 4 (KEY_PROG*) and your hardware does not event
generate the 5th so there ;)

>
> > >3. Do nothing.
> >
> > Well, probably not nothing. Map it to KEY_UNKNOWN and have userspace
> > listen to such events and inform user when it presses such a key that
> > such and such happened and tell him how to map it to something useful.
>
> Not optimal, but certainly much better than "do nothing".  I will go with
> this one, if I can't have my extra FN keys or PROG keys.
>

OK.

> That said, how is one to know which hardware key was translated to
> KEY_UNKNOWN, so that he can inform the user to remap that key?  Should I
> send another event together with KEY_UNKNOWN that has the raw keycode? Which
> one?
>

You may try using EV_MSC/MSC_SCAN. You can even send it all the time,
not only for KEY_UNKNOWN.

> > >I *REALLY* do not like (3), and so far I have not seen a single good
> > >technical reason to go with it.
> >
> > Reasons: do not require expaning current keymap preserving space for
> > more useful keycodes.
>
> We should either reclaim space then (remove all of KEY_FN_* and make them
> KEY_PROG* generic stuff), or double the entire keycode space (add one bit to
> KEY_MAX) so that new keycodes can be added for a while.  Declaring a keycode
> crunch on drivers when one gets close to exausting each bit of KEY_MAX is
> not a solution IMHO.

We have space for about 30-40 more functional events (0x1b*, parts of
0x1c* and 0x1d*) so using them wisely we should last for a while. I
think we have most relevant parts of HID usage tables covered. KEY_MAX
and the rest of KEY_* are exported to userspace, that's why we can't
remove any existing definitions and I am hesitant to change KEY_MAX.

>
> > > From the technically sound ones, you need
> > >to either have the keycodes you need for (2) (i.e. KEY_FN_BACKSPACE), or a
> > >big enough set of keycodes to use (1) (i.e. KEY_PROG5..KEY_PROGn, where n
> > >should probably be at least 8).
> >
> > Why 8? Why not 16? Or 32 just to make sure?
>
> Eight is a bare minimum (and enough for my needs if the KEY_FN already there
> don't go away :p), but I already told you that if it were up to me, I'd
> convert all of FN_ to such codes, and cover 0x1d0 to 0x1ef with them, which
> gives us 32 generic codes.  We would have 36 KEY_PROG then, which hopefully
> would be enough for a while.
>
> > >> I really don't like KEY_FN_F1..KEY_FN_BACKSPACE either. What are they
> > >> supposed to do? Just being an unique value to be mapped onto something
> > >> useful? But why not use that useful keycode to begin with?
> > >
> > >Yes, just an unique value to be mapped onto something useful, by something
> > >in userspace.  Just like KEY_PROG, actually.
> >
> > In _every_ program that gets events directly?
>
> Yes.  It is not nearly as nice as functional key codes (like KEY_WLAN), but
> it is better than KEY_UNKONWN or wrong keys.   Of course, if you *know* a
> key's function, you use that.

I guess we have different opinions. For me KEY_UNKNOWN is better
because it encourages user to adjust keymap table in the kernel at
startup (or at hotplug time) and then rest of userspace does not need
to be aware at all about host specific settings. Most higher level
keymaps will work automatically when kernel emits "functional" events.
Userspace is only responsible for translating combinations of events
(i.e. when someone presses KEY_A with shift held it means capital A.
But it works for all devices that have key A on them).

>
> > >One can't use a "useful keycode" for two reasons:
> > >
> > >1.      Because the key has no set function (it is unmarked)
> > >2.      Because it has, or could have, a set function, but we have no clue
> > >which is it.
> >
> > KEY_UNKNOWN then.
>
> KEY_UNKNOWN requires that userspace remap it for it to be usable.
>

As well as KEY_PROG* or KEY_FN*. It is just the mapping happens on
different level.

> > >> I'd rather leave the keys unmapped and rely on initsripts (possibly
> > >> with help from distributions vendors) to load proper keymap then add
> > >> something that must be retranslated over and over again.
> > >
> > >I don't.  I can live with it, of course, but if we are going to go that
> > >way,
> > >what IS the excuse for a big lot of the keys already in input.h?  We have
> > >been adding the unique keycodes and functional keycodes because it is
> > >*useful*.
> >
> > Because they most of them describe an expected _action_ that would
> > happend after keypress.
>
> But why can't we get those that do NOT do that and are not around most
> keyboards to be completely generic, then?
>

We have a few of them and I think that is more than enough.

Consider ejecting a CD tray. You have a laptop with a key that maked
eject CD. Because it is a new laptop there are no proper mapping yet
so some adjustments are needed. With your scenario the kernel emits
KEY_PROG26. User has first to adjust X keymap to map KEY_PROG26 to
EjectCD event (simplifying). Then he goes into text console only to
find out that his curses-based CD player does not recognize that key
and also needs to be adjusted. And so on. Finally all applications are
made aware of KEY_PROG26 amd user is happy. Couple of weeks later he
goes and buys an external keyboard and it turns out that eject CD
there is actually KEY_PROG21 so he need to go through second round of
mapping for all applications. Not only that but button with volume
increase happens to generate KEY_PROG26. Now what?

Now consider in-kernel remapping to functional scancdes that I
propose: user says that that key should generate KEY_EJECTCD and it
starts working in all appliations recognizing that event. Adding the
second keyboard into mix does not mess up the first one.

> > [...skipped...]
> > >
> > >> And what are their intended functions would be? How KEY_VENDORHOMEPAGE
> > >> is different from KEY_HOMEPAGE?
> > >
> > >KEY_VENDORHOMEPAGE is exactly that.  It is marked with the vendor's name.
> > >KEY_HOMEPAGE has a defined function inherited from that other O.S. which is
> > >to open up the default browser on the default "homepage".  I can easily see
> > >both keys existing on a system.
> > >
> >
> > OK, right now we have:
> >
> > KEY_WWW
> > KEY_VENDOR
> > KEY_HOMEPAGE
> >
> > defines in input.h. Are you sayign that none of these would suit?
>
> KEY_VENDOR would work for me.  I had not searched around for one yet, and I
> would have found it out before sending you a patch asking for
> KEY_VENDORHOMEPAGE.
>
> KEY_PROG, on the other hand, looked to me like an function (like program
> macro or whatever).
>
> > >As for stuff like KEY_FN_BACKSPACE, well, I don't really care, as long as I
> > >have *something* unique and not incorrect to use.  But if we are not going
> > >to add extra KEY_FN_ keycodes, why don't we just convert them all to
> > >KEY_PROG, so that they can be useful to all and not just to people who have
> > >FN_<whatever> keys?
> >
> > We could add aliases if you really want...
>
> If you add aliases to the whole FN block, and add a few more KEY_PROG to
> fill the holes so that the entire 0x1d0-0x1ef range is usable by
> thinkpad-acpi, that would be enough for me.  I am not sure how that is any
> better (or any worse) than the other possible solutions that change input.h,
> though.
>
> > Can you tell me on _your_ thinkpad what markings you have? I mean
>
> http://www.thinkwiki.org/wiki/Default_meanings_of_special_keys
>
> Mine is a T43.  That table is not 100% correct, the T43 doesn't label the
> fn+f8 or fn+f9 keys.  And it is still very very much incomplete.
>
> > there should be a common pattern on thinkpads and the rest may be
> > guessed (you mentioned that FN-F5 is used to turn off radio quite
> > often so if thinkpad driver detects radio switch it makes sence to
> > just go ahead and mark FN-F5 as KEY_WLAN, doesn't it?)
>
> For that particular key, yes... until we find out a thinkpad that has that
> key elsewhere.
>

That may or may not happen. So far I can see some patterns -
brightnell control seems to be in same place, sleep, etc.

-- 
Dmitry

Re: [ibm-acpi-devel] [PATCH] ACPI: thinkpad-acpi: add thinkpad keys to input.h

[Matthew Garrett]

On Wed, May 30, 2007 at 04:25:03PM -0400, Dmitry Torokhov wrote:

> Consider ejecting a CD tray. You have a laptop with a key that maked
> eject CD. Because it is a new laptop there are no proper mapping yet
> so some adjustments are needed. With your scenario the kernel emits
> KEY_PROG26. User has first to adjust X keymap to map KEY_PROG26 to
> EjectCD event (simplifying). Then he goes into text console only to
> find out that his curses-based CD player does not recognize that key
> and also needs to be adjusted. And so on. Finally all applications are
> made aware of KEY_PROG26 amd user is happy. Couple of weeks later he
> goes and buys an external keyboard and it turns out that eject CD
> there is actually KEY_PROG21 so he need to go through second round of
> mapping for all applications. Not only that but button with volume
> increase happens to generate KEY_PROG26. Now what?
> 
> Now consider in-kernel remapping to functional scancdes that I
> propose: user says that that key should generate KEY_EJECTCD and it
> starts working in all appliations recognizing that event. Adding the
> second keyboard into mix does not mess up the first one.

That makes absolute sense when a key has a defined function, but in the
case we're discussing it doesn't. So, we have two choices:

1) Map it to a specific function system-wide (so a default of 
KEY_UNKNOWN is fine)
2) Map it to a specific function at the user level

If the key doesn't have anything printed on it, there is no correct 
system-wide default. It's intrinsically a per-user preference. But for 
the user to be able to decide what the key does, it has to generate a 
keycode. Once it does that they can use one of the existing X 
applications to bind that to an X keysym and then everyone is happy.

But for this to be possible a keycode has to be generated. We can either 
set this at boot time or in the kernel. The only argument for doing it 
at boot time is that userspace might have a better idea what the key 
should map to. However, in the case of a blank key, how is userspace 
going to have any more idea than the kernel does? The only sane default 
is something like KEY_PROG1.

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

Making KEY_UNKNOWN really useful to userland

[Henrique de Moraes Holschuh]

On Wed, 30 May 2007, Dmitry Torokhov wrote:
> On 5/30/07, Henrique de Moraes Holschuh <hmh@hmh.eng.br> wrote:
> >It is trivial to guarantee that KEY_PROG is unique for a single input
> >device (keyboard), but it certainly won't work across multiple devices.
> >Userspace has to know what kind of input device it is talking to to map
> >them to something, but since the input layer already provides this
> >information, I was not going to raise a fuss about it.  I figure it is
> >the price of not increasing even more the keycode table.
> 
> Actually I try to discourage people from using input_id during device
> discovery but rather tell them to analyze capability bits and then decide
> if their application is interested in that particular input device. I
> think input_id should pretty much only used by udev & co. to adjust
> default kernel setup for the needs of local installation (fix keymap,
> adjust absmax, etc).

It is likely going to be used by something like udev, or an init script, or
a thinkpad-configurator helper, or whatever.  Sounds like the sort of stuff
that should be paying attention to input_id anyway.

We don't appear to have deployed a good kernel-userland interface that
allows us to have generic "press an unknown key and tell me what you want it
to do" application in userland, but if we do please correct me.  If
KEY_UNKNOWN was always required to send a EV_MSC MSC_RAW/MSC_SCAN, then we
would have one.

Maybe we can add that requirement and driver changes (if any, for all I know
most drivers might already be generating such events) for 2.6.23?  I bet
Richard would like that one a lot.  Richard?

Such functionality makes most of my requests for new keycodes irrelevant, so
I will just trim that down.

> >That said, how is one to know which hardware key was translated to
> >KEY_UNKNOWN, so that he can inform the user to remap that key?  Should I
> >send another event together with KEY_UNKNOWN that has the raw keycode?
> >Which one?
> 
> You may try using EV_MSC/MSC_SCAN. You can even send it all the time, not
> only for KEY_UNKNOWN.

Will do, thanks.  And I will send it all the time, that will force people to
properly implement code that can deal with them in userland.

What is the exact difference between MSC_RAW and MSC_SCAN?  Which one can be
used as an index to reprogram the keymap using the IOCTLs?

> I guess we have different opinions. For me KEY_UNKNOWN is better because
> it encourages user to adjust keymap table in the kernel at startup (or at
> hotplug time) and then rest of userspace does not need to be aware at all

If we add a requirement and fix all EV_KEY drivers to always report the scan
code (or raw code, I still don't know which is which) that allows an
userspace application to know what keymap position to change to fix that
key, so that we can have an app that:

1. gets a EV_KEY KEY_UNKNOWN and its related EV_MSC MSC_? event
2. offers the user to map it, now that it knows how to do so.

(note that, for the above to work right, the application must really tap
into all input devices so that it knows exactly which one is reporting the
event, etc).

I will readly agree with you, KEY_UNKNOWN will definately be the right
choice for anything that is not a functional key and which doesn't have
something like FN_foo already in input.h (and maybe even if does have a
FN_foo keycode already in input.h).

> Consider ejecting a CD tray. You have a laptop with a key that maked eject
> CD. Because it is a new laptop there are no proper mapping yet so some
> adjustments are needed. With your scenario the kernel emits KEY_PROG26.
> User has first to adjust X keymap to map KEY_PROG26 to EjectCD event
> (simplifying). Then he goes into text console only to find out that his
> curses-based CD player does not recognize that key and also needs to be
> adjusted. And so on. Finally all applications are made aware of KEY_PROG26
> amd user is happy. Couple of weeks later he goes and buys an external
> keyboard and it turns out that eject CD there is actually KEY_PROG21 so he
> need to go through second round of mapping for all applications. Not only
> that but button with volume increase happens to generate KEY_PROG26. Now
> what?

Yes, that is the problem with non-functional keys if we don't have a
position-specific keycode for all of them (like FN_F1).

> Now consider in-kernel remapping to functional scancdes that I propose:
> user says that that key should generate KEY_EJECTCD and it starts working
> in all appliations recognizing that event. Adding the second keyboard into
> mix does not mess up the first one.

I got your point.  So, we should have PROG* free for the user to assign to
keys, but never use it by default.

-- 
  "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: Making KEY_UNKNOWN really useful to userland

[Dmitry Torokhov]

On Wednesday 30 May 2007 20:53, Henrique de Moraes Holschuh wrote:
> On Wed, 30 May 2007, Dmitry Torokhov wrote:
> > On 5/30/07, Henrique de Moraes Holschuh <hmh@hmh.eng.br> wrote:
> > >It is trivial to guarantee that KEY_PROG is unique for a single input
> > >device (keyboard), but it certainly won't work across multiple devices.
> > >Userspace has to know what kind of input device it is talking to to map
> > >them to something, but since the input layer already provides this
> > >information, I was not going to raise a fuss about it.  I figure it is
> > >the price of not increasing even more the keycode table.
> > 
> > Actually I try to discourage people from using input_id during device
> > discovery but rather tell them to analyze capability bits and then decide
> > if their application is interested in that particular input device. I
> > think input_id should pretty much only used by udev & co. to adjust
> > default kernel setup for the needs of local installation (fix keymap,
> > adjust absmax, etc).
> 
> It is likely going to be used by something like udev, or an init script, or
> a thinkpad-configurator helper, or whatever.  Sounds like the sort of stuff
> that should be paying attention to input_id anyway.

Right.

> 
> We don't appear to have deployed a good kernel-userland interface that
> allows us to have generic "press an unknown key and tell me what you want it
> to do" application in userland, but if we do please correct me.  If
> KEY_UNKNOWN was always required to send a EV_MSC MSC_RAW/MSC_SCAN, then we
> would have one.
>

Yes, I think this is a resonable requrement.

> Maybe we can add that requirement and driver changes (if any, for all I know
> most drivers might already be generating such events) for 2.6.23?

I think that we should start with drivers that allow adjusting keymaps
via EVIOCGKEYCODE/EVIOCSKEYCODE. If driver does not allow changing keymap
then it does not really matter (although I will try to convert drivers
now that we have getkeycode/setkeycode per-device methods).
 
> I bet 
> Richard would like that one a lot.  Richard?
> 
> Such functionality makes most of my requests for new keycodes irrelevant, so
> I will just trim that down.
> 
> > >That said, how is one to know which hardware key was translated to
> > >KEY_UNKNOWN, so that he can inform the user to remap that key?  Should I
> > >send another event together with KEY_UNKNOWN that has the raw keycode?
> > >Which one?
> > 
> > You may try using EV_MSC/MSC_SCAN. You can even send it all the time, not
> > only for KEY_UNKNOWN.
> 
> Will do, thanks.  And I will send it all the time, that will force people to
> properly implement code that can deal with them in userland.
> 
> What is the exact difference between MSC_RAW and MSC_SCAN?  Which one can be
> used as an index to reprogram the keymap using the IOCTLs?
>

MSC_RAW is just raw data from device. It may carry make/break data encoded
in it. MSC_SCAN is what one need.

-- 
Dmitry

Re: Making KEY_UNKNOWN really useful to userland

[Richard Hughes]

On Wed, 2007-05-30 at 21:53 -0300, Henrique de Moraes Holschuh wrote:
> Maybe we can add that requirement and driver changes (if any, for all
> I know most drivers might already be generating such events) for
> 2.6.23?  I bet Richard would like that one a lot.  Richard?

To be honest, I've got lost in all the discussion about hotkeys. What is
the plan for a typical acpi driver?

i.e. what do you want a driver to emit given two scenarios:

* A acpi event that is always the same on all models?
   KEY_BRIGHTNESSUP?

* an acpi event that is different on every laptop model?
   KEY_PROG1? KEY_UNKNOWN?

Tell me what do to, and I'll resync my trees and resubmit patches.

Thanks.



-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/

Re: Making KEY_UNKNOWN really useful to userland

[Henrique de Moraes Holschuh]

On Thu, 31 May 2007, Richard Hughes wrote:
> On Wed, 2007-05-30 at 21:53 -0300, Henrique de Moraes Holschuh wrote:
> > Maybe we can add that requirement and driver changes (if any, for all
> > I know most drivers might already be generating such events) for
> > 2.6.23?  I bet Richard would like that one a lot.  Richard?
> 
> To be honest, I've got lost in all the discussion about hotkeys. What is
> the plan for a typical acpi driver?
> 
> i.e. what do you want a driver to emit given two scenarios:
> 
> * A acpi event that is always the same on all models?
>    KEY_BRIGHTNESSUP?

When one should be sent, yes.  It has the same problem as a volume
up/down/mute key that "just works" in firmware: you don't want to have two
things trying to mess with the display brightness every time a brightness
key is pressed.

SOME keys have the added aggravation that they really, really should be
sending ACPI events instead (brightness up/down is one: it is an ACPI 3.0a
event), but to really get that to work, we need to improve how ACPICA talks
to other ACPI modules to selectively disable some functions.

But that's not a problem that affects every hot key in every platform out
there, so I consider them to be the exceptions that define the rule :-p

> * an acpi event that is different on every laptop model?
>    KEY_PROG1? KEY_UNKNOWN?

EV_KEY KEY_UNKNOWN + EV_MSC MSC_SCAN (or MSC_RAW??) + EV_SYN for *unmarked*
keys.  Then you just ask the user if he wants to map that scan code to some
other keycode in userspace, if you want.

For thinkpad-acpi, I don't send ACPI events for stuff I will be sending a
meaningful input event, just like you asked me to (and I don't send events
if nothing has the input device open).  So you get ACPI events if nothing is
listening to the input device, OR if the key is unmapped or mapped to
KEY_UNKNOWN.

I will send the scan code always in thinkpad-acpi, but that is hardly
necessary I suppose.

Note that the scan code is the same for press and release (it is the same
key).  So anything that wants to know if a key was pressed or released
better use the EV_KEY to know it (as it should, since it *is* in the same
event block for a damn good reason :p ).

Oh, and the thinkpad firmware 'weirdness' of needing one to enable/disable
OS hot key support still applies, of course (the hotkey mask).

> Tell me what do to, and I'll resync my trees and resubmit patches.

I am on it on the thinkpad-acpi side, so at least for that, you don't have
to worry.  I am still waiting an answer about which event is the correct one
to output scancodes, but the thinkpad-acpi GIT tree is already updated with
the above, tentively using MSC_SCAN to report scan codes.

-- 
  "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: Making KEY_UNKNOWN really useful to userland

[Dmitry Torokhov]

On 5/31/07, Henrique de Moraes Holschuh <hmh@hmh.eng.br> wrote:
> On Thu, 31 May 2007, Richard Hughes wrote:
>
> I am on it on the thinkpad-acpi side, so at least for that, you don't have
> to worry.  I am still waiting an answer about which event is the correct one
> to output scancodes, but the thinkpad-acpi GIT tree is already updated with
> the above, tentively using MSC_SCAN to report scan codes.
>

I thought I sent out email saying MSC_SCAN is what you want to use,
MSC_RAW is raw data from device, potentially having make/break codes
included/encoded. Apparently my mail broke even more than I thought.

Highjacking the thread somewhat - Richard, I saw your patch for
toshiba_acpi. Please use input-polldev to set up polled devices. It
will create work queue for you and will make sure that polling is
stopped when device is closed. Also I don't think you want to use
KEY_BREAK. What is the expected function of that key?

Please copy me on input-related changes in the tree. Thank you.

-- 
Dmitry

[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, 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

[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, 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

[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

[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

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