From patchwork Tue Dec 17 15:48:54 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Herrmann X-Patchwork-Id: 3362371 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.19.201]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 33D20C0D4A for ; Tue, 17 Dec 2013 15:50:11 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 42161203AA for ; Tue, 17 Dec 2013 15:50:06 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 2EB5B203A7 for ; Tue, 17 Dec 2013 15:50:04 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754558Ab3LQPtd (ORCPT ); Tue, 17 Dec 2013 10:49:33 -0500 Received: from mail-ee0-f43.google.com ([74.125.83.43]:50313 "EHLO mail-ee0-f43.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754872Ab3LQPta (ORCPT ); Tue, 17 Dec 2013 10:49:30 -0500 Received: by mail-ee0-f43.google.com with SMTP id c13so2945167eek.16 for ; Tue, 17 Dec 2013 07:49:28 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=q+oZ+gWOIgFJ1/SAJl+33AZJldFbg2vjdU/Nl/U8x5M=; b=yYYH/Vb/U4mldoFcmIpDtEEVbfI6JdaIFlraX/dVVYoWQJg3kkkxduBzUW6HPe6Fdh pADv+jWvYgMZSVDEYvx4P6MpBO3yrh0nDVFVWErk1e+fWLmI4j8kejiMWUo8ti/jdfkb IkGvpQ2mb4nL9dw4dhU9M4kyjeA7/dIcOoOrJBgof9IIdsPWqyPQb1ZQPumtklZ/cMXW U6pJMxpYAFRM4mUsH/87mV38pzocSCUzsXy/jOJPkQeZqYxmrg97nPQ7JvAryNB7oOY/ mEPAaU2OGnIXna0rBbPYFnid6AnJtmwFdrwbBH1AyEnOMWzNzhyF1PtGYdIT344E8K99 r5TA== X-Received: by 10.14.87.2 with SMTP id x2mr23415074eee.79.1387295368708; Tue, 17 Dec 2013 07:49:28 -0800 (PST) Received: from david-ub.localdomain (stgt-4d024e4a.pool.mediaWays.net. [77.2.78.74]) by mx.google.com with ESMTPSA id l4sm54116077een.13.2013.12.17.07.49.26 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 17 Dec 2013 07:49:27 -0800 (PST) From: David Herrmann To: linux-input@vger.kernel.org Cc: Dmitry Torokhov , Jiri Kosina , Benjamin Tissoires , Peter Hutterer , Antonio Ospite , linux-kernel@vger.kernel.org, input-tools@lists.freedesktop.org, David Herrmann Subject: [PATCH 4/4] Input: add motion-tracking ABS_* bits and docs Date: Tue, 17 Dec 2013 16:48:54 +0100 Message-Id: <1387295334-1744-5-git-send-email-dh.herrmann@gmail.com> X-Mailer: git-send-email 1.8.5.1 In-Reply-To: <1387295334-1744-1-git-send-email-dh.herrmann@gmail.com> References: <1387295334-1744-1-git-send-email-dh.herrmann@gmail.com> Sender: linux-input-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-input@vger.kernel.org X-Spam-Status: No, score=-7.3 required=5.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED, FREEMAIL_FROM, RCVD_IN_DNSWL_HI, RP_MATCHES_RCVD, T_DKIM_INVALID, UNPARSEABLE_RELAY autolearn=unavailable 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 Motion sensors are getting quite common in mobile devices. To avoid returning accelerometer data via ABS_X/Y/Z and irritating the Xorg mouse-driver, this adds separate ABS_* bits for that. This is needed if gaming devices want to report their normal data plus accelerometer/gyro data. Usually, ABS_X/Y are already used by analog sticks, so need separate definitions, anyway. Signed-off-by: David Herrmann --- Documentation/input/gamepad.txt | 7 ++ Documentation/input/motion-tracking.txt | 149 ++++++++++++++++++++++++++++++++ include/linux/mod_devicetable.h | 2 +- include/uapi/linux/input.h | 9 +- 4 files changed, 165 insertions(+), 2 deletions(-) create mode 100644 Documentation/input/motion-tracking.txt diff --git a/Documentation/input/gamepad.txt b/Documentation/input/gamepad.txt index 196dc42..eeda685 100644 --- a/Documentation/input/gamepad.txt +++ b/Documentation/input/gamepad.txt @@ -57,6 +57,9 @@ Most gamepads have the following features: - Rumble Many devices provide force-feedback features. But are mostly just simple rumble motors. + - Motion-tracking + Gamepads may include motion-tracking sensors like accelerometers and + gyroscopes. 3. Detection ~~~~~~~~~~~~ @@ -153,5 +156,9 @@ Menu-Pad: Rumble: Rumble is adverticed as FF_RUMBLE. +Motion-tracking: + Motion-tracking is defined in ./Documentation/input/motion-tracking.txt and + gamepads shall comply to the rules defined there. + ---------------------------------------------------------------------------- Written 2013 by David Herrmann diff --git a/Documentation/input/motion-tracking.txt b/Documentation/input/motion-tracking.txt new file mode 100644 index 0000000..0885c9a --- /dev/null +++ b/Documentation/input/motion-tracking.txt @@ -0,0 +1,149 @@ + Motion Tracking API +---------------------------------------------------------------------------- + +1. Intro +~~~~~~~~ +Motion tracking devices produce device motion events generated from an +accelerometer, gyroscope or compass. This data can be returned to user-space +via input events. This document defines how this data is reported. + +2. Devices +~~~~~~~~~~ +In this document, a "device" is one of: + - accelerometer + - gyroscope + - compass + +These devices returned their information via different APIs in the past. To +unify them and define a common API, a set of input evdev codes was created. Old +drivers might continue using their API, but developers are encouraged to use +the input evdev API for new drivers. + +2.1 Axes +~~~~~~~~ +Movement data is usually returned as absolute data for the 3 axes of a device. +In this context, the three axes are defined as: + - X: Axis goes from the left to the right side of the device + - Y: Axis goes from the bottom to the top of the device + - Z: Axis goes from the back to the front of the device + +The front of a device is the side faced to the user. For a mobile-phone it +would be the screen. For devices without a screen, the front is usually the +side with the most buttons on it. + + Example: Mobile-Phone + +-------------------------------------------------------------------------+ + | TOP | + | | + | | + | +---------------------------+ | + | |\ ________________________ \ .__ | + | \ \ \ \ \ |\ | + | \ \ \ __ \ \ \ RIGHT| + | \ \ \ /| \ \ \__ | + | \ \ \ __/ \ \ |\ | + | \ \ \ /| \ \ \ (Y Axis) | + | \ \ \ __/ (Z axis) \ \ \__ | + | \ \ \ /| \ \ |\ | + | LEFT \ \ \ / \ \ \ | + | \ \ \ FRONT \ \ \ | + | \ \ \ \ \ | + | \ \ \_______________________\ \ | + | \ \ ___ \ | + | /\ \ \__\ \ | + | __/ \ +---------------------------+ | + | /| \|___________________________| | + | / BACK | + | (X axis) | + | ------->------->------->-------> | + | | + | | + | BOTTOM | + +-------------------------------------------------------------------------+ + +Rotation-data is reported as clock-wise rotation on an axis. For a given axes, +the reported rotation would be: + ___ + /| + / | (axis) + / + .-**-. + / / \ + | / \ | / + \ / \|/ (clock-wise rotation) + / + / + / + +2.2 Calibration +~~~~~~~~~~~~~~~ +Motion sensors are often highly sensitive and need precise calibration. Users +are adviced to perform neutral-point calibration themselves or to implement a +state-machine to normalize input data automatically. + +Kernel devices may perform their own calibration and/or normalization. However, +this is usually sparse and, if implemented, transparent to the user. + +There is currently no way to feed calibration data into the kernel in a generic +way. Proposals welcome! + +2.3 Units +~~~~~~~~~ +(NOTE: This section describes an experimental API. Currently, no device complies +to these rules so this might change in the future.) + +Reported data shall be returned as: + - Acceleration: 1/1000 m per s^2 + - Rotation: 1/1000 degree per second + +However, for most devices the reported units are unknown (more precisely: no +one has the time to measure them and figure them out). Therefore, user-space +shall use abs-minimum and abs-maximum to calculate relative data and use that +instead. Devices which return wrong units may be fixed in the future to comply +to these rules. + +3.1 Accelerometer +~~~~~~~~~~~~~~~~~ +Accelerometers measure movement acceleration of devices. Any combination of the +three available axes can be used. Usually, all three are supported. + +Data is provided as absolute acceleration. A positive integer defines the +acceleration in the direction of an axis. A negative integer defines +acceleration in the opposite direction. + +The evdev ABS codes used are: + - ABS_ACCEL_X: X axis + - ABS_ACCEL_Y: Y axis + - ABS_ACCEL_Z: Z axis + +3.2 Gyroscope +~~~~~~~~~~~~~ +A gyroscope measures rotational speed (*not* acceleration!). Any combination of +the three available axes can be used. Usually, all three are supported. + +Data is provided as absolute speed. A positive integer defines the rotational +speed in clock-wise order around a given axis. A negative integer defines it in +counter-clock-wise order. + +The evdev ABS codes used are: + - ABS_GYRO_X: X axis (also: Pitch) + - ABS_GYRO_Y: Y axis (also: Roll) + - ABS_GYRO_Z: Z axis (also: Azimuth/Yaw) + +3.3 Compass +~~~~~~~~~~~ +(NOTE: No compass device currently uses the evdev input subsystem. Thus, this +API is only a proposal, it hasn't been implemented, yet.) + +A compass measures the ambient magnetic field of the three defined axes. This +makes the data self-contained and independent of the current device position. +Any combination of the three axes can be used. Usually all three are supported, +otherwise, it's not really useful as a compass. + +Proposed evdev ABS codes are: + - ABS_COMPASS_X: X axis + - ABS_COMPASS_Y: Y axis + - ABS_COMPASS_Z: Z axis + +---------------------------------------------------------------------------- + Written 2013 by David Herrmann diff --git a/include/linux/mod_devicetable.h b/include/linux/mod_devicetable.h index 45e9214..329aa30 100644 --- a/include/linux/mod_devicetable.h +++ b/include/linux/mod_devicetable.h @@ -277,7 +277,7 @@ struct pcmcia_device_id { #define INPUT_DEVICE_ID_KEY_MIN_INTERESTING 0x71 #define INPUT_DEVICE_ID_KEY_MAX 0x2ff #define INPUT_DEVICE_ID_REL_MAX 0x0f -#define INPUT_DEVICE_ID_ABS_MAX 0x3f +#define INPUT_DEVICE_ID_ABS_MAX 0x4f #define INPUT_DEVICE_ID_MSC_MAX 0x07 #define INPUT_DEVICE_ID_LED_MAX 0x0f #define INPUT_DEVICE_ID_SND_MAX 0x07 diff --git a/include/uapi/linux/input.h b/include/uapi/linux/input.h index 1856461..e4c3596 100644 --- a/include/uapi/linux/input.h +++ b/include/uapi/linux/input.h @@ -869,12 +869,19 @@ struct input_keymap_entry { #define ABS_MAX 0x3f #define ABS_CNT (ABS_MAX+1) +#define ABS_ACCEL_X 0x40 /* Accelerometer X axis */ +#define ABS_ACCEL_Y 0x41 /* Accelerometer Y axis */ +#define ABS_ACCEL_Z 0x42 /* Accelerometer Z axis */ +#define ABS_GYRO_X 0x43 /* Gyroscope X axis */ +#define ABS_GYRO_Y 0x44 /* Gyroscope Y axis */ +#define ABS_GYRO_Z 0x45 /* Gyroscope Z axis */ + /* * Due to API restrictions the legacy evdev API only supports ABS values up to * ABS_MAX/CNT. Use the extended *ABS2 ioctls to operate on any ABS values in * between ABS_MAX and ABS_MAX2. */ -#define ABS_MAX2 0x3f +#define ABS_MAX2 0x4f #define ABS_CNT2 (ABS_MAX2+1) /*