Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN (v2)
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 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN (v2)
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 - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN (v2)
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 <[EMAIL PROTECTED]> > Cc: Dmitry Torokhov <[EMAIL PROTECTED]> > Cc: Richard Hughes <[EMAIL PROTECTED]> > --- > > 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 <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]> Signed-off-by: Dmitry Torokhov <[EMAIL PROTECTED]> --- 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: - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN (v2)
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 [EMAIL PROTECTED] Cc: Dmitry Torokhov [EMAIL PROTECTED] Cc: Richard Hughes [EMAIL PROTECTED] --- 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] Signed-off-by: Dmitry Torokhov [EMAIL PROTECTED] --- 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: - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN (v2)
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 <[EMAIL PROTECTED]> Cc: Dmitry Torokhov <[EMAIL PROTECTED]> Cc: Richard Hughes <[EMAIL PROTECTED]> --- 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 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCH] Input: document the proper usage of EV_KEY and KEY_UNKNOWN (v2)
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 [EMAIL PROTECTED] Cc: Dmitry Torokhov [EMAIL PROTECTED] Cc: Richard Hughes [EMAIL PROTECTED] --- 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 - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
