From patchwork Fri Nov 1 20:16:15 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Herrmann X-Patchwork-Id: 3127591 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.19.201]) by patchwork1.web.kernel.org (Postfix) with ESMTP id D09AF9F3C4 for ; Fri, 1 Nov 2013 20:16:56 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id A1843204C9 for ; Fri, 1 Nov 2013 20:16:55 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id E2DAB204D2 for ; Fri, 1 Nov 2013 20:16:53 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753229Ab3KAUQv (ORCPT ); Fri, 1 Nov 2013 16:16:51 -0400 Received: from mail-ea0-f171.google.com ([209.85.215.171]:35011 "EHLO mail-ea0-f171.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752553Ab3KAUQu (ORCPT ); Fri, 1 Nov 2013 16:16:50 -0400 Received: by mail-ea0-f171.google.com with SMTP id h10so2276555eak.30 for ; Fri, 01 Nov 2013 13:16:49 -0700 (PDT) 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=TQ1g92JFr/pQCJvOb4mBPIku1wUuKio1o5S4Oe7/g/s=; b=duUbKCAsnpI0+dQGgZ6YEEp8pFLUfMBS0AGZF1Duax4EaCFnT0BDi2zB4yKABlfAFf 3upuwY9DMAnGVeRYnW8Biu77+nhB4+3JHOQC5czchEyo6V1X22JuhvIRzItx6LZhnB4C 4Mdi5dpfxJT0IIMJYvdioccrqQnxWnz3Qp1526zojuKkfgcpCUMFfvhAft4hSRp7kifQ y305mOrbD2tP9Gdj5iQBrgm/zTH8a5LeSom+cDMK+YKKf+LRerVXQ9pQ+aOw4NpRnzm+ ELa5XHL2yqzamayMTZF/vBOyOgCwTmpUBoDrTBXOFbCCkUBnFJ7jxxZMIH5cqy7SqFf5 Wlsw== X-Received: by 10.14.182.72 with SMTP id n48mr764099eem.113.1383337009260; Fri, 01 Nov 2013 13:16:49 -0700 (PDT) Received: from localhost.localdomain (stgt-5f719f65.pool.mediaWays.net. [95.113.159.101]) by mx.google.com with ESMTPSA id i1sm11797335eeg.0.2013.11.01.13.16.47 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Nov 2013 13:16:48 -0700 (PDT) From: David Herrmann To: linux-input@vger.kernel.org Cc: Dmitry Torokhov , Jiri Kosina , Peter Hutterer , Benjamin Tissoires , David Herrmann Subject: [PATCH 04/13] Input: add motion-tracking ABS_* bits and docs Date: Fri, 1 Nov 2013 21:16:15 +0100 Message-Id: <1383336984-26601-5-git-send-email-dh.herrmann@gmail.com> X-Mailer: git-send-email 1.8.4.1 In-Reply-To: <1383336984-26601-1-git-send-email-dh.herrmann@gmail.com> References: <1383336984-26601-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=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 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 c40b109..bd168c0 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 ~~~~~~~~~~~~ @@ -150,5 +153,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 9e525f9..f347498 100644 --- a/include/uapi/linux/input.h +++ b/include/uapi/linux/input.h @@ -863,12 +863,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) /*