Add ff-memless-next module
Subsystems (3)
PATCH v4 1/1 Add ff-memless-next module
Introduce ff-memless-next module as a possible future replacement for ff-memless.
Cc <[email protected]>
Cc <[email protected]>
Cc Rob Landley <[email protected]>
Tested-by Elias Vanderstuyft <[email protected]>
Signed-off-by Michal Malý <[email protected]>
---
v4: Fix a typo in the documentation file
v3: Use proper email format
v2: Remove unnecessary "else" branches
Documentation/input/ff-memless-next.txt | 149 ++++++ drivers/input/Kconfig | 12 + drivers/input/Makefile | 2 + drivers/input/ff-memless-next.c | 793 ++++++++++++++++++++++++++++++++ include/linux/input/ff-memless-next.h | 31 ++ 5 files changed, 987 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 +149 -0
@@ -0,0 +1,149 @@ +"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" +module and its purpose. This document also contains a summary +of the "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" effect is really being played or not. +"Uncombinable" effects are FF_DAMPER, FF_FRICTION, FF_INERTIA and FF_SPRING. + +FF_CUSTOM is currently not handled by "ff-memless-next". + +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 be 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 +793 -0
793 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