Add ff-memless-next
Subsystems (3)
RFC v3 1/1 Add ff-memless-next
One case where uncombinable effects were mishandled was corrected. Rest of the changes are just coding style fixes.
---
From 2de27604adeefa73e30ee049fae4c38265beb85d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michal=20Mal=C3=BD?= <[email protected]>
Date: Mon, 23 Dec 2013 23:42:11 +0100
Subject: [PATCH] Add ff-memless-next
--- Documentation/input/ff-memless-next.txt | 145 ++++++ drivers/input/Kconfig | 12 + drivers/input/Makefile | 2 + drivers/input/ff-memless-next.c | 786 ++++++++++++++++++++++++++++++++ include/linux/input/ff-memless-next.h | 31 ++ 5 files changed, 976 insertions(+) create mode 100644 Documentation/input/ff-memless-next.txt create mode 100644 drivers/input/ff-memless-next.c create mode 100644 include/linux/input/ff-memless-next.h
Documentation/input/ff-memless-next.txt new file +145 -0
@@ -0,0 +1,145 @@ +"ff-memless-next" force feedback module for memoryless devices. +By Michal Malý <[email protected]> on 2013/12/21 +---------------------------------------------------------------------------- + +1. Introduction +~~~~~~~~~~~~~~~ +This document describes basic working principles of the "ff-memless-next" +and its purpose. This document also contains summary of "ff-memless-next" API +and brief instructions on how to use it to write a hardware-specific backend +with "ff-memless-next". Some specifics of ff-memless-next that might be of +interest for userspace developers are also discussed. + +2. Basic principles of ff-memless-next +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A lot of commonly used force feedback devices do not have a memory of their +own. This means that it is not possible to upload a force feedback effect +to such a device and let the device's CPU handle the playback. Instead, +the device relies solely on its driver to tell it what force to generate. +"ff-memless-next" was written to serve in this capacity. Its purpose is to +calculate the overall force the device should apply and pass the result to +a hardware-specific backend which then submits the appropriate command to +the device. + +"ff-memless-next" differentiates between two types of force feedback effects, +"combinable" and "uncombinable". +"Combinable" effects are effects that generate a force of a given +magnitude and direction. The magnitude can change in time according to the +envelope of the effect and its waveform; the latter applies only to periodic +effects. Force generated by "combinable" effect does not depend on the position +of the device. Forces generated by each "combinable" effect that is active +are periodically recalculated as needed and superposed into one overall force. +"Combinable" effects are FF_CONSTANT, FF_PERIODIC and FF_RAMP. + +"Uncombinable" effects generate a force that depends on the position of +the device. "ff-memless-next" assumes that the device takes care of processing +such an effect. However, a device might have a limit on how many "uncombinable" +effects can be active at once and this limit might be lower than the maximum +effect count set in "ff-memless-next". "ff-memless-next" allows a +hardware-specific driver to check whether the device is able to play +an "uncombinable" effect. Error is reported back to userspace if the device +cannot play the effect. The hardware-specific driver may choose not to +perform this check in which case the userspace will have no way of knowing +whether an "uncombinable" is really being played or not. + +3. API provided by "ff-memless-next" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +"ff-memless-next" provides an API for developers of hardware-specific +drivers. In order to use the API, the hardware-specific driver should +include <linux/input/ff-memless-next.h> +Functions and structs defined by this API are: + +int input_ff_create_mlnx(struct input_dev *dev, void *data, + int(*control_effect)(struct input_dev *, void *, const struct mlnx_effect_command *), + const u16 update_rate) +- Any hardware-specific driver that wants to use "ff-memless-next" must call +this function. The function takes care of creating and registering a force +feedback device within the kernel. It also initializes resources needed by +"ff-memless-next" to handle a new device. No other initialization steps are necessary. + Parameters: + * dev - pointer to valid struct input_dev + * data - pointer to custom data the hardware-specific backend + might need to pass to the control_effect() callback function + (discussed later). * data will be freed automatically by + "ff-memless-next" upon device's destruction. + * control_effect - A callback function. "ff-memless-next" will call + this function when it is done processing effects. + Implementation of control_effect() in the + hardware-specific driver should create an appropriate + command and submit it to the device. + This function is called with dev->event_lock + spinlock held. + update_rate - Rate in milliseconds at which envelopes and periodic + effects are recalculated. Minimum value is limited by the + kernel timer resolution and changes with value of + CONFIG_HZ. + +struct mlnx_effect_command +^^^^^^^^^^^^^^^^^^^^^^^^^^ +- This struct is passed to the hardware-specific backend in +the control_effect() function. See "ff-memless-next.h" for details. + +enum mlnx_commands +^^^^^^^^^^^^^^^^^^ +- Types of commands generated by ff-memless-next + MLNX_START_COMBINED - Start or update "combinable" effect + MLNX_STOP_COMBINED - Stop "combinable" effect. In most cases this means + to set the force to zero. + MLNX_UPLOAD_UNCOMB - Check if the device can accept and play + "uncombinable" effect. + Hardware-specific driver should return 0 + on success. + MLNX_START_UNCOMB - Start playback of "uncombinable" effect. + MLNX_STOP_UNCOMB - Stop playback of "uncombinable" effect. + +struct mlnx_simple_force +^^^^^^^^^^^^^^^^^^^^^^^^ + x - overall force along X axis + y - overall force along Y axis + +struct mlnx_uncomb_effect +^^^^^^^^^^^^^^^^^^^^^^^^^ +- Information about "uncombinable" effect. + id - internal ID of the effect + * effect - pointer to the internal copy of the effect kept by + "ff-memless-next". This pointer will remain valid until + the effect is removed. + +Sample implementation of a dummy driver that uses "ff-memless-next" is +available at "git://prifuk.cz/ff-dummy-device". Link to the source will +be kept up to date. + +Direction of the effect's force translates to Cartesian coordinates system +as follows: + Direction = 0: Down + Direction (0; 16384): 3rd quadrant + Direction = 16384: Left + Direction (16385; 32768): 2nd quadrant + Direction = 32768: Up + Direction (32769; 49152): 1st quadrant + Direction = 49152: Right + Direction (49153; 65535) :4th quadrant + Direction = 65565: Down + +4. Specifics of "ff-memless-next" for userspace developers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +None of the persons involved in development or testing of "ff-memless-next" +is aware of any reference force feedback specifications. "ff-memless-next" +tries to adhere to Microsoft's DirectInput specifications because we +believe that is what most developers have experience with. + +- Waveforms of periodic effects do not start at the origin, but as follows: + SAW_UP: At minimum + SAW_DOWN: At maximum + SQUARE: At maximum + TRIANGLE: At maximum + SINE: At origin + +- Updating periodic effects: + - All periodic effects are restarted when their parameters are updated. + +- Updating effects of finite duration: + - Once an effect of finite length finishes playing, it is considered + stopped. Only effects that are playing can be updated on the fly. + Therefore effects of finite duration can by updated only until + they finish playing.
drivers/input/Kconfig +12 -0
@@ -77,6 +77,18 @@ config INPUT_MATRIXKMAP To compile this driver as a module, choose M here: the module will be called matrix-keymap. +config INPUT_FF_MEMLESS_NEXT + tristate "New version of support for memoryless force feedback devices" + help + Say Y here if you want to enable support for various memoryless + force feedback devices (as of now there is no hardware-specific + driver that supports this) + + If unsure, say N. + + To compile this driver as a module, choose M here: the + module will be called ff-memless-next. + comment "Userland interfaces" config INPUT_MOUSEDEV
drivers/input/Makefile +2 -0
@@ -16,6 +16,8 @@ obj-$(CONFIG_INPUT_MOUSEDEV) += mousedev.o obj-$(CONFIG_INPUT_JOYDEV) += joydev.o obj-$(CONFIG_INPUT_EVDEV) += evdev.o obj-$(CONFIG_INPUT_EVBUG) += evbug.o +obj-$(CONFIG_INPUT_MATRIXKMAP) += matrix-keymap.o +obj-$(CONFIG_INPUT_FF_MEMLESS_NEXT) += ff-memless-next.o obj-$(CONFIG_INPUT_KEYBOARD) += keyboard/ obj-$(CONFIG_INPUT_MOUSE) += mouse/
drivers/input/ff-memless-next.c new file +786 -0
786 lines not on this page · raw message
include/linux/input/ff-memless-next.h new file +31 -0
@@ -0,0 +1,31 @@ +#include <linux/input.h> + +enum mlnx_commands { +MLNX_START_COMBINED , +MLNX_STOP_COMBINED , +MLNX_START_UNCOMB , +MLNX_STOP_UNCOMB , +MLNX_UPLOAD_UNCOMB +}; + +struct mlnx_simple_force { +const s32 x; +const s32 y; +}; + +struct mlnx_uncomb_effect { +const int id; +const struct ff_effect *effect; +}; + +struct mlnx_effect_command { +const enum mlnx_commands cmd; +union { +const struct mlnx_simple_force simple_force; +const struct mlnx_uncomb_effect uncomb; + } u; +}; + +int input_ff_create_mlnx (struct input_dev *dev,void *data, +int (*control_effect)(struct input_dev *,void *,const struct mlnx_effect_command *), +const u16 update_rate);
Signature · 7 lines
1.8.5.2 -- To unsubscribe from this list: send the line "unsubscribe linux-input" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 2 lines · Michal Malý
One case where uncombinable effects were mishandled was corrected. Rest of the changes are just coding style fixes.
trivia:
drivers/input/ff-memless-next.c
Quoted 1 line
drivers/input/ff-memless-next.c +0
-0
[]
drivers/input/ff-memless-next.c
Quoted 2 lines
drivers/input/ff-memless-next.c +2
-0+static __always_inline s32 mlnx_calculate_x_force(const s32 level, +const u16 direction)
__always_inline is almost never warranted.
gcc generally does the right thing.
--
To unsubscribe from this list: send the line "unsubscribe linux-input" in the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 9 lines · On Monday 23 of December 2013 16:21:48 you wrote:
Quoted 2 lines · Michal Malý
One case where uncombinable effects were mishandled was corrected. Rest of the changes are just coding style fixes.
trivia:
drivers/input/ff-memless-next.c
Quoted 2 lines
drivers/input/ff-memless-next.c +0
-0[]
Quoted 5 lines
drivers/input/ff-memless-next.c
Quoted 2 lines
drivers/input/ff-memless-next.c +2
-0+static __always_inline s32 mlnx_calculate_x_force(const s32 level, +const u16 direction)
__always_inlineis almost never warranted.
gcc generally does the right thing.
I did some reading about __always_inline vs. plain inline and I ran into some contradictory information about what is considered broken. Thanks for letting me know...
Is there anything else that needs some reviewing?
--
To unsubscribe from this list: send the line "unsubscribe linux-input" in the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Randy Dunlap
reviewerQuoted 17 lines · Michal Malý
--- Documentation/input/ff-memless-next.txt | 145 ++++++ drivers/input/Kconfig | 12 + drivers/input/Makefile | 2 + drivers/input/ff-memless-next.c | 786 ++++++++++++++++++++++++++++++++ include/linux/input/ff-memless-next.h | 31 ++ 5 files changed, 976 insertions(+) create mode 100644 Documentation/input/ff-memless-next.txt create mode 100644 drivers/input/ff-memless-next.c create mode 100644 include/linux/input/ff-memless-next.hDocumentation/input/ff-memless-next.txt new file +0
-0
Documentation/input/ff-memless-next.txt line 7
Quoted 7 lines
Documentation/input/ff-memless-next.txt new file +7
-0@@ -0,0 +1,145 @@ +"ff-memless-next" force feedback module for memoryless devices. +By Michal Malý <[email protected]> on 2013/12/21 +---------------------------------------------------------------------------- + +1. Introduction +~~~~~~~~~~~~~~~ +This document describes basic working principles of the "ff-memless-next"
driver
(or module)
Documentation/input/ff-memless-next.txt line 8
Quoted 1 line
Documentation/input/ff-memless-next.txt new file +1
-0+and its purpose. This document also contains summary of "ff-memless-next" API
a summary of the
Quoted 11 lines
Documentation/input/ff-memless-next.txt new file +3
-0+and brief instructions on how to use it to write a hardware-specific backend +with "ff-memless-next". Some specifics of ff-memless-next that might be of +interest for userspace developers are also discussed.drivers/input/Kconfig +0
-0
drivers/input/Kconfig config INPUT_MATRIXKMAP · line 85
Quoted 9 lines
drivers/input/Kconfig +6
-0@@ -77,6 +77,18 @@ config INPUT_MATRIXKMAP To compile this driver as a module, choose M here: the module will be called matrix-keymap. +config INPUT_FF_MEMLESS_NEXT + tristate "New version of support for memoryless force feedback devices" + help + Say Y here if you want to enable support for various memoryless + force feedback devices (as of now there is no hardware-specific + driver that supports this)
this).
Quoted 9 lines
drivers/input/Kconfig +6
-0+ + If unsure, say N. + + To compile this driver as a module, choose M here: the + module will be called ff-memless-next. + comment "Userland interfaces" config INPUT_MOUSEDEV
Signature · 5 lines
~Randy -- To unsubscribe from this list: send the line "unsubscribe linux-input" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html