From patchwork Thu Oct 8 09:57:27 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Hauke Pribnow X-Patchwork-Id: 7351001 Return-Path: X-Original-To: patchwork-linux-input@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id DB97BBEEA4 for ; Thu, 8 Oct 2015 09:57:47 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id C3B2F207CE for ; Thu, 8 Oct 2015 09:57:46 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id AE5A3207CD for ; Thu, 8 Oct 2015 09:57:45 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751859AbbJHJ5o (ORCPT ); Thu, 8 Oct 2015 05:57:44 -0400 Received: from mout.gmx.net ([212.227.17.22]:63624 "EHLO mout.gmx.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751688AbbJHJ5n (ORCPT ); Thu, 8 Oct 2015 05:57:43 -0400 Received: from [127.0.0.1] ([77.20.148.56]) by mail.gmx.com (mrgmx103) with ESMTPSA (Nemesis) id 0MZlEg-1a2KWW3mhy-00LSle; Thu, 08 Oct 2015 11:57:35 +0200 From: Hauke Pribnow Subject: [1/2 v2] Input: input.h - Add and extend KEY_* usage detail comments To: linux-input@vger.kernel.org Cc: anssi.hannula@iki.fi Message-ID: <56163E07.4000705@gmx.net> Date: Thu, 8 Oct 2015 11:57:27 +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:TMu95K+SJUvAOis8K9H721Zt2lAl3Lt01C2HQ7EHnx8PKizWybN Bih0yOkVQJ1twlSYqFaAwzgJtmEsAlMBqqURU60X/L9kFYhFRKAzEim6Gbnzr/3UnGfj0C1 0L3ZkqsE5d6CE09y+0RAQq45V1gwE/eiGhvdEwRYdwgsbYCQXh0U9uoFBlAXT0nHbwPx/NV Kl0rIxH3c2zL3d9ueOTig== X-UI-Out-Filterresults: notjunk:1; V01:K0:fRXcZjKe03U=:4i3HN1TE/ZKSl93hk5N1a9 Grk3atZpi7APwlQorE1xnrD0jReNS23rHTaWyalxZ2g+tX5/nMO3HsrQNlWN8cRU/Dt9aDd9T u49ONnqNAsh9Y53QEqfKJp4ECekQww/23vkuEPOF3EoZPdyJH2/AWyhnwakpJ0AfTmFhvX/P7 P/q6kauvj8G7ubJOsDu4L2+UvQLMpCOyYZzttii5eL+qmuXbNHl/L8SYvYdKmR61Wm0F8gnxI wRZ+nPMedEkyxAtiuyQKnkP/oO3vHMDSU5DbMVdaQewY0bO5MV2KfQR7ERzJoiifmZy4ne8xo dHffSOE5mrUeJzOYuwbu4l/2l+AUwznkMf1i+WCKs/pvAGyA+pA3Q1eY5H/6S0hgafGUDaQXh ITSXEzG37qcoB74J+ZAziFKkpu1ZCnV2aYrcv68SM5hekgQ+BtwIC+NVF/EEM8OzGiHv3ktto TK52b5boKnbNOKAem7Qu4OlYT43u7Y5Ib/qayZ77ycbIkUsYbViD2eJIRZaq4xH7bfs6v9WkO pnWetM4WmnzbZek35+YPk1c/v18wcmQLzDefnTQdfh7hKF1Ok0akrRIPC9Mo0kXivNBtubQKc cV7MfACek+EnXXO5jPyv6BKkrt7werEZV3WlVkHg97fa5X3oSmyRP7bUg+6Sj1omVe2I2tQ86 6fJeq5VsAHw34vT8knzNceDKLaOfLOfXRvodPhlcN75rPyfuKWRDjSL1b08p9yyqsOl6H6iGD CKKNYFvjOCrJxDxRxIpExrbZVVuG1fjVYpcELpTRbA8nio+ZuvPYTKUqoUQx8wQlK+s2jTsB9 lvmPGiU 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 --- (This is a re-submission because my e-mail client broke the patch by wrapping long lines. Sorry for that!) 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(-) 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 */ #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 */