patch-2.4.10 linux/Documentation/input/ff.txt

• Lines: 195
• Date: Wed Sep 12 15:34:06 2001
• Orig file: v2.4.9/linux/Documentation/input/ff.txt
• Orig date: Wed Dec 31 16:00:00 1969

diff -u --recursive --new-file v2.4.9/linux/Documentation/input/ff.txt linux/Documentation/input/ff.txt
@@ -0,0 +1,194 @@
+Force feedback for Linux.
+By Johann Deneux <deneux@ifrance.com> on 2001/04/22.
+
+----------------------------------------------------------------------------
+
+0. Introduction
+~~~~~~~~~~~~~~~
+This document describes how to use force feedback devices under Linux. The
+goal is not to support these devices as if they were simple input-only devices
+(as it is already the case), but to really enable the rendering of force
+effects.
+At the moment, only I-Force devices are supported, and not officially. That
+means I had to find out how the protocol works on my own. Of course, the
+information I managed to grasp is far from being complete, and I can not
+guarranty that this driver will work for you.
+This document only describes the force feedback part of the driver for I-Force
+devices. Please read joystick.txt before reading further this document.
+
+2. Instructions to the user
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Here are instructions on how to compile and use the driver. In fact, this
+driver is the normal iforce.o, input.o and evdev.o drivers written by Vojtech
+Pavlik, plus additions to support force feedback.
+
+Before you start, let me WARN you that some devices shake violently during the
+initialisation phase. This happens for example with my "AVB Top Shot Pegasus".
+To stop this annoying behaviour, move you joystick to its limits. Anyway, you
+should keep a hand on your device, in order to avoid it to brake down if
+something goes wrong.
+
+At the kernel's compilation:
+	- Enable IForce/Serial
+	- Enable Event interface
+
+Compile the modules, install them.
+
+You also need inputattach.
+
+You then need to insert the modules into the following order:
+% modprobe joydev
+% modprobe serport
+% modprobe iforce
+% modprobe evdev
+% ./inputattach -ifor $2 &	# Only for serial
+For convenience, you may use the shell script named "ff" available from
+the cvs tree of the Linux Console Project at sourceforge. You can also
+retrieve it from http://www.esil.univ-mrs.fr/~jdeneux/projects/ff/.
+If you are using USB, you don't need the inputattach step.
+
+Please check that you have all the /dev/input entries needed:
+cd /dev
+rm js*
+mkdir input
+mknod input/js0 c 13 0
+mknod input/js1 c 13 1
+mknod input/js2 c 13 2
+mknod input/js3 c 13 3
+ln -s input/js0 js0
+ln -s input/js1 js1
+ln -s input/js2 js2
+ln -s input/js3 js3
+
+mknod input/event0 c 13 64
+mknod input/event1 c 13 65
+mknod input/event2 c 13 66
+mknod input/event3 c 13 67
+
+2.1 Does it work ?
+~~~~~~~~~~~~~~~~~~
+There is an utility called fftest that will allow you to test the driver.
+% fftest /dev/eventXX
+
+3. Instructions to the developper
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  All interactions are done using the event API. That is, you can use ioctl()
+and write() on /dev/input/eventXX.
+  This information is subject to change.
+
+3.1 Querying device capabilities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#include <linux/input.h>
+#include <sys/ioctl.h>
+
+int ioctl(int file_descriptor, int request, unsigned long *features);
+
+"request" must be EVIOCGBIT(EV_FF, sizeof(unsigned long))
+
+Returns the features supported by the device. features is a bitfield with the
+following bits:
+- FF_X		has an X axis (should allways be the case)
+- FF_Y		has an Y axis (usually not the case for wheels)
+- FF_CONSTANT	can render constant force effects
+- FF_PERIODIC	can render periodic effects (sine, ramp, square...)
+- FF_SPRING	can simulate the presence of a spring
+- FF_FRICTION	can simulate friction (aka drag, damper effect...)
+- FF_RUMBLE	rumble effects (normally the only effect supported by rumble
+		pads)
+- 8 bits from FF_N_EFFECTS_0 containing the number of effects that can be
+		simultaneously played.
+
+3.2 Uploading effects to the device
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#include <linux/input.h>
+#include <sys/ioctl.h>
+ 
+int ioctl(int file_descriptor, int request, struct ff_effect *effect);
+
+"request" must be EVIOCSFF.
+
+"effect" points to a structure describing the effect to upload. The effect is
+uploaded, but not played.
+The content of effect may be modified. In particular, its field "id" is set
+to the unique id assigned by the driver. This data is required for performing
+some operations (removing an effect, controlling the playback).
+See <linux/input.h> for a description of the ff_effect stuct.
+
+3.3 Removing an effect from the device
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+int ioctl(int fd, EVIOCRMFF, effect.id);
+
+This makes room for new effects in the device's memory. Please note this won't
+stop the effect if it was playing.
+
+3.4 Controlling the playback of effects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Control of playing is done with write(). Below is an example:
+
+#include <linux/input.h>
+#include <unistd.h>
+
+	struct input_event play;
+	struct input_event stop;
+	struct ff_effect effect;
+	int fd;
+...
+	fd = open("/dev/input/eventXX", O_RDWR);
+...
+	/* Play three times */
+	play.type = EV_FF;
+	play.code = effect.id;
+	play.value = 3;
+	
+	write(fd, (const void*) &play, sizeof(play));
+...
+	/* Stop an effect */
+	stop.type = EV_FF;
+	stop.code = effect.id;
+	stop.value = 0;
+	
+	write(fd, (const void*) &play, sizeof(stop));
+
+3.5 Setting the gain
+~~~~~~~~~~~~~~~~~~~~
+Not all devices have the same strength. Therefore, users should set a gain
+factor depending on how strong they want effects to be. This setting is
+persistent accross access to the driver, so you should not care about it if
+you are writing games, as another utility probably already set this for you.
+
+/* Set the gain of the device
+int gain;		/* between 0 and 100 */
+struct input_event ie;	/* structure used to communicate with the driver */
+
+ie.type = EV_FF;
+ie.code = FF_GAIN;
+ie.value = 0xFFFFUL * gain / 100;
+
+if (write(fd, &ie, sizeof(ie)) == -1)
+	perror("set gain");
+
+3.6 Enabling/Disabling autocenter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The autocenter feature quite disturbs the rendering of effects in my opinion,
+and I think it should be an effect, which computation depends on the game
+type. But you can enable it if you want.
+
+int autocenter;		/* between 0 and 100 */
+struct input_event ie;
+
+ie.type = EV_FF;
+ie.code = FF_AUTOCENTER;
+ie.value = 0xFFFFUL * autocenter / 100;
+
+if (write(fd, &ie, sizeof(ie)) == -1)
+	perror("set auto-center");
+
+A value of 0 means "no auto-center".
+
+3.7 Dynamic update of an effect
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This consists in changing some parameters of an effect while it's playing. The
+driver currently does not support that. You still have the brute-force method,
+which consists in erasing the effect and uploading the updated version. It
+actually works pretty well. You don't need to stop-and-start the effect.
+