From patchwork Thu Oct 8 09:06:54 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Hauke Pribnow X-Patchwork-Id: 7350541 Return-Path: X-Original-To: patchwork-linux-input@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 0B33A9F32B for ; Thu, 8 Oct 2015 09:07:14 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id E795B207C2 for ; Thu, 8 Oct 2015 09:07:12 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id A7CD1207BD for ; Thu, 8 Oct 2015 09:07:11 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753997AbbJHJHK (ORCPT ); Thu, 8 Oct 2015 05:07:10 -0400 Received: from mout.gmx.net ([212.227.15.18]:56484 "EHLO mout.gmx.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752880AbbJHJHG (ORCPT ); Thu, 8 Oct 2015 05:07:06 -0400 Received: from [127.0.0.1] ([77.20.148.56]) by mail.gmx.com (mrgmx003) with ESMTPSA (Nemesis) id 0LkgAG-1aIM3F3r7M-00aRsA; Thu, 08 Oct 2015 11:07:02 +0200 From: Hauke Pribnow Subject: [1/2] Input: input.h - Add and extend KEY_* usage detail comments To: linux-input@vger.kernel.org Cc: anssi.hannula@iki.fi Message-ID: <5616322E.4040807@gmx.net> Date: Thu, 8 Oct 2015 11:06:54 +0200 User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:38.0) Gecko/20100101 Thunderbird/38.3.0 MIME-Version: 1.0 X-Antivirus: avast! (VPS 151007-2, 07.10.2015), Outbound message X-Antivirus-Status: Clean X-Provags-ID: V03:K0:HtyLT+8JCPDYq4UVUeuTOO1mA+PFaTCN6iWpO8cjxhU84/7GXno 9ECoFeAZgdpqDrYqo2loudW2pxtbqLJQ59hzLoUnLAIvWlZ3B1K/rj/brQ0Gqs0BUgActD4 VtTOe4RALKUJuzVNdI8Az1eSdFXdWacgi2YLBpnlXSEQUxjOCBmOcPwigdpeiyUFVLI6YCK IApayAXOjRi3JLlDb2vxQ== X-UI-Out-Filterresults: notjunk:1; V01:K0:ck0PkzGFjDY=:7g0DsxGeLwHJQgW5CqJsbC uLV5ZtuZuDdMCCju59D1Th0E4wZIj13eeS1GuvuRldhlnrR6L9XCXX+zbaZ3VAoSnPz6xPDWZ h5u1QlRwEVjL5Flt6Coht4WoJn/wmsJwKJdkA0Wf32Z1klt1l09vKJlvEUxeM5hZHCrMM/y6h 8PpHScEIUilO4t+rxgSNlPOO7Q6LSj4Kc6RQG7K6FhyIeQTRf4GTOT59tc8pi4Z88xtc8U65I 1Rpq8w2fMhvHENWw+H9fWgnPTLXd4ZRmPG6PlMBlAV/PoaKnyDwZawtfdHQYoOiwFa0tOiWS9 SY5gVS2JjniZHPUI33CMdQNGq7YJOtQYODeY6wBiRNv8g/PVBZmck8XT9VYHkouNAyBA4LcIR GuLFdWSkFShuTSTe9eZQLa8z+ZcNAIwuCzdnf6mbKxaeAZDtENSCHhSefKwrMQq73D8YBeLo1 fevvoYyxJfAqfaBoLwskYPrpb5ps9peAfdHIcA41za4CMqjrQAttagbtwVI2Cy64om6K0ftHO 8+IjNKCFl2zhwgUN5s+86xZZxKL4RpjHVS7f9zjFR80eFV06bMoGeeYSF+ea2qVzwRSz9TEH0 PC05yr90QO/zsO3lXBl53jTdCCw6n3B5mnfbblU696sefbJNQFBji2DhqPMqIx4H0my5qsOIu QIYJQ+KfWwDqjggIqjfzk6Twz34A19fgnFMpIyEgZ2m4eoOOWjuWS5CXFcsp+n7ROpPRnouIA omxDiQTNg6S0aTiN59kHR6bj6VWPNADYu8De8Fru2sRkRAzKduGe5GsmbyRlEjN0Wh4Z9vuUE fiqigP1 Sender: linux-input-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-input@vger.kernel.org X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00,FREEMAIL_FROM, RCVD_IN_DNSWL_HI,T_RP_MATCHES_RCVD,UNPARSEABLE_RELAY autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP The KEY_* definitions in input.h had no formal functional definitions when they were first introduced. This led to a situation where some keys were used very inconsistently across different drivers. For example, KEY_SETUP was used both in some very low-level situations (like resetting the settings to the device defaults or to lauch some system backup tool for some integrated devices) and on high-level home media remote controls (where the key should open some kind of configuration window). To reach a more consistent usage of KEY_* definitions, it is crucial to add and extend comments in input.h to assign functional key definitions to KEY_* definitions, preferrably based on the USB HID Usage Tables for keys that are not defined in such a way yet. This patch adds such funtional definitions for KEY_SETUP, KEY_CONFIG and KEY_CONTROLPANEL. It further adds some information on how these definitions are related to each other. Signed-off-by: Hauke Pribnow --- Hello everyone, first of all: I hope that I read enough about "The Process" so that I did not make any mistake in submitting this patch. This is my first Linux kernel patch ever - so please bear with me. Here's some more details that made me create this patch: I'm currently revising the keytable for a home media USB RF remote I own. During this process I got into contact with the original kernel driver module author who created the first keytable for this remote. He reviewed my proposed changes and agreed with most of my changes except of one: We ended up being confused about the meaning of the KEY_SETUP and KEY_CONFIG definitions in input.h. Since the input.h does not contain any information on what the functional definitions behind the KEY_* definitions are, I got into contact with the original author of the input.h file, Vojt?ch Pavlík, and asked for his opinion. He clarified that the KEY_* definitions had no formal definitions when they were first introduced. He concluded that it's basically about retro-defining what the keys mean. In my initial mail to him I proposed the definitions for KEY_SETUP and KEY_CONFIG like in the patch at hand to him. Fortunately he agreed in his reply that the reasoning behind my definitions makes sense. So I went ahead and created this first patch of two. Thanks a lot for any kind of feedback in advance, Hauke include/uapi/linux/input.h | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) #define KEY_WAKEUP 143 /* System Wake Up */ #define KEY_FILE 144 /* AL Local Machine Browser */ @@ -388,7 +392,14 @@ struct input_keymap_entry { #define KEY_REWIND 168 #define KEY_PHONE 169 /* Media Select Telephone */ #define KEY_ISO 170 -#define KEY_CONFIG 171 /* AL Consumer Control Configuration */ +#define KEY_CONFIG 171 /* AL Consumer Control Configuration + (USB HID Usage Tables 15.15). Such + a tool should allow associating + keys/buttons with a consumer + device. KEY_CONTROLPANEL should be + assigned to keys that are intended + for more generic configuration + applications. */ #define KEY_HOMEPAGE 172 /* AC Home */ #define KEY_REFRESH 173 /* AC Refresh */ #define KEY_EXIT 174 /* AC Exit */ @@ -737,7 +748,12 @@ struct input_keymap_entry { #define KEY_BUTTONCONFIG 0x240 /* AL Button Configuration */ #define KEY_TASKMANAGER 0x241 /* AL Task/Project Manager */ #define KEY_JOURNAL 0x242 /* AL Log/Journal/Timecard */ -#define KEY_CONTROLPANEL 0x243 /* AL Control Panel */ +#define KEY_CONTROLPANEL 0x243 /* AL Control Panel (USB HID + Usage Tables 15.15). Use + this instead of KEY_SETUP + for application- or + operating system- level + configuration tasks. */ #define KEY_APPSELECT 0x244 /* AL Select Task/Application */ #define KEY_SCREENSAVER 0x245 /* AL Screen Saver */ #define KEY_VOICECOMMAND 0x246 /* Listening Voice Command */ diff --git a/include/uapi/linux/input.h b/include/uapi/linux/input.h index 731417c..ffb232a 100644 --- a/include/uapi/linux/input.h +++ b/include/uapi/linux/input.h @@ -356,7 +356,11 @@ struct input_keymap_entry { #define KEY_HELP 138 /* AL Integrated Help Center */ #define KEY_MENU 139 /* Menu (show menu) */ #define KEY_CALC 140 /* AL Calculator */ -#define KEY_SETUP 141 +#define KEY_SETUP 141 /* SC System Setup, i.e. enter BIOS- + level system (USB HID Usage Tables + 4.5.1). KEY_CONTROLPANEL makes more + sense for application- or operating + system-level configuration tasks. */ #define KEY_SLEEP 142 /* SC System Sleep */