diff mbox

[04/13] Input: add motion-tracking ABS_* bits and docs

Message ID 1383336984-26601-5-git-send-email-dh.herrmann@gmail.com
State New, archived
Headers show

Commit Message

David Herrmann Nov. 1, 2013, 8:16 p.m. UTC
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 <dh.herrmann@gmail.com>
---
 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

Comments

Antonio Ospite Nov. 15, 2013, 10:11 a.m. UTC | #1
On Fri,  1 Nov 2013 21:16:15 +0100
David Herrmann <dh.herrmann@gmail.com> wrote:

> 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 <dh.herrmann@gmail.com>

Hi, what's the status of this patch?
I cannot see it in Dmitry's repository, David maybe you have another
repository I can pull from? 

Thanks,
   Antonio
David Herrmann Nov. 15, 2013, 10:17 a.m. UTC | #2
Hi Antonio

On Fri, Nov 15, 2013 at 11:11 AM, Antonio Ospite
<ospite@studenti.unina.it> wrote:
> On Fri,  1 Nov 2013 21:16:15 +0100
> David Herrmann <dh.herrmann@gmail.com> wrote:
>
>> 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 <dh.herrmann@gmail.com>
>
> Hi, what's the status of this patch?
> I cannot see it in Dmitry's repository, David maybe you have another
> repository I can pull from?

Please see patch 1/13 and 2/13. They fix the kernel ABI to support new
ABS_* bits (the current ABI is broken in that regard). As this is
quite critical and caused breaks during the last merge-window, we
haven't merged it yet. I hope to get it into 3.14, though. The current
patches seem fine and work for me. I will try to get the user-space
part working in the next weeks.

Any help is welcome!

Thanks
David
--
To unsubscribe from this list: send the line "unsubscribe linux-input" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Antonio Ospite Nov. 16, 2013, 5:53 p.m. UTC | #3
On Fri, 15 Nov 2013 11:17:31 +0100
David Herrmann <dh.herrmann@gmail.com> wrote:

> Hi Antonio
> 
> On Fri, Nov 15, 2013 at 11:11 AM, Antonio Ospite
> <ospite@studenti.unina.it> wrote:
> > On Fri,  1 Nov 2013 21:16:15 +0100
> > David Herrmann <dh.herrmann@gmail.com> wrote:
> >
> >> 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 <dh.herrmann@gmail.com>
> >
> > Hi, what's the status of this patch?
> > I cannot see it in Dmitry's repository, David maybe you have another
> > repository I can pull from?
> 
> Please see patch 1/13 and 2/13. They fix the kernel ABI to support new
> ABS_* bits (the current ABI is broken in that regard). As this is
> quite critical and caused breaks during the last merge-window, we
> haven't merged it yet. I hope to get it into 3.14, though. The current
> patches seem fine and work for me. I will try to get the user-space
> part working in the next weeks.
> 
> Any help is welcome!
> 

I can try updating evtest, any idea about how I should check at
runtime whether ABS_MAX2 is supported or not?

Ciao,
   Antonio
David Herrmann Nov. 16, 2013, 6:07 p.m. UTC | #4
Hi

On Sat, Nov 16, 2013 at 6:53 PM, Antonio Ospite
<ospite@studenti.unina.it> wrote:
> On Fri, 15 Nov 2013 11:17:31 +0100
> David Herrmann <dh.herrmann@gmail.com> wrote:
>
>> Hi Antonio
>>
>> On Fri, Nov 15, 2013 at 11:11 AM, Antonio Ospite
>> <ospite@studenti.unina.it> wrote:
>> > On Fri,  1 Nov 2013 21:16:15 +0100
>> > David Herrmann <dh.herrmann@gmail.com> wrote:
>> >
>> >> 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 <dh.herrmann@gmail.com>
>> >
>> > Hi, what's the status of this patch?
>> > I cannot see it in Dmitry's repository, David maybe you have another
>> > repository I can pull from?
>>
>> Please see patch 1/13 and 2/13. They fix the kernel ABI to support new
>> ABS_* bits (the current ABI is broken in that regard). As this is
>> quite critical and caused breaks during the last merge-window, we
>> haven't merged it yet. I hope to get it into 3.14, though. The current
>> patches seem fine and work for me. I will try to get the user-space
>> part working in the next weeks.
>>
>> Any help is welcome!
>>
>
> I can try updating evtest, any idea about how I should check at
> runtime whether ABS_MAX2 is supported or not?

That's still my current issue that I need to fix. My intention is to
increase EVDEV_VERSION, so EVIOCGVERSION will suffice to test for it.

Thanks
David
--
To unsubscribe from this list: send the line "unsubscribe linux-input" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
diff mbox

Patch

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 <dh.herrmann@gmail.com>
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 <dh.herrmann@gmail.com>
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)
 
 /*