Skip to contentSkip to conversation

Add ff-memless-next

RFC In review Michal Malý 3 participants 4 messages Dec 23, 2013 – Dec 24, 2013

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

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
new file mode 100644
index 0000000..00f893d
@@ -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
index a11ff74..893ab00 100644
@@ -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
index 5ca3f63..269a22d 100644
@@ -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
new file mode 100644
index 0000000..f2fb080
@@ -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
#1 lore raw
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

#2 lore raw
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_inline is 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

reviewer
#3 lore raw
In reply to Michal Malý
Quoted 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.h
Documentation/input/ff-memless-next.txt new file +0 -0
new file mode 100644
index 0000000..00f893d

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
index a11ff74..893ab00 100644

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