diff options
Diffstat (limited to 'Documentation/input/ff.txt')
| -rw-r--r-- | Documentation/input/ff.txt | 221 |
1 files changed, 0 insertions, 221 deletions
diff --git a/Documentation/input/ff.txt b/Documentation/input/ff.txt deleted file mode 100644 index b3867bf49f8f..000000000000 --- a/Documentation/input/ff.txt +++ /dev/null @@ -1,221 +0,0 @@ -Force feedback for Linux. -By Johann Deneux <johann.deneux@gmail.com> on 2001/04/22. -Updated by Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09. -You may redistribute this file. Please remember to include shape.fig and -interactive.fig as well. ----------------------------------------------------------------------------- - -1. 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. -This document only describes the force feedback part of the Linux input -interface. Please read joystick.txt and input.txt before reading further this -document. - -2. Instructions to the user -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To enable force feedback, you have to: - -1. have your kernel configured with evdev and a driver that supports your - device. -2. make sure evdev module is loaded and /dev/input/event* device files are - created. - -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 break down if -something goes wrong. - -If you have a serial iforce device, you need to start inputattach. See -joystick.txt for details. - -2.1 Does it work ? -~~~~~~~~~~~~~~~~~~ -There is an utility called fftest that will allow you to test the driver. -% fftest /dev/input/eventXX - -3. Instructions to the developer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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> - -#define BITS_TO_LONGS(x) \ - (((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long))) -unsigned long features[BITS_TO_LONGS(FF_CNT)]; -int ioctl(int file_descriptor, int request, unsigned long *features); - -"request" must be EVIOCGBIT(EV_FF, size of features array in bytes ) - -Returns the features supported by the device. features is a bitfield with the -following bits: -- FF_CONSTANT can render constant force effects -- FF_PERIODIC can render periodic effects with the following waveforms: - - FF_SQUARE square waveform - - FF_TRIANGLE triangle waveform - - FF_SINE sine waveform - - FF_SAW_UP sawtooth up waveform - - FF_SAW_DOWN sawtooth down waveform - - FF_CUSTOM custom waveform -- FF_RAMP can render ramp effects -- FF_SPRING can simulate the presence of a spring -- FF_FRICTION can simulate friction -- FF_DAMPER can simulate damper effects -- FF_RUMBLE rumble effects -- FF_INERTIA can simulate inertia -- FF_GAIN gain is adjustable -- FF_AUTOCENTER autocenter is adjustable - -Note: In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All - devices that support FF_RUMBLE support FF_PERIODIC (square, triangle, - sine) and the other way around. - -Note: The exact syntax FF_CUSTOM is undefined for the time being as no driver - supports it yet. - - -int ioctl(int fd, EVIOCGEFFECTS, int *n); - -Returns the number of effects the device can keep in its memory. - -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). -This if field must be set to -1 by the user in order to tell the driver to -allocate a new effect. - -Effects are file descriptor specific. - -See <linux/input.h> for a description of the ff_effect struct. You should also -find help in a few sketches, contained in files shape.fig and interactive.fig. -You need xfig to visualize these files. - -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. Note that this also -stops 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 across access to the driver. - -/* 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Proceed as if you wanted to upload a new effect, except that instead of -setting the id field to -1, you set it to the wanted effect id. -Normally, the effect is not stopped and restarted. However, depending on the -type of device, not all parameters can be dynamically updated. For example, -the direction of an effect cannot be updated with iforce devices. In this -case, the driver stops the effect, up-load it, and restart it. - -Therefore it is recommended to dynamically change direction while the effect -is playing only when it is ok to restart the effect with a replay count of 1. - -3.8 Information about the status of effects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Every time the status of an effect is changed, an event is sent. The values -and meanings of the fields of the event are as follows: - -struct input_event { -/* When the status of the effect changed */ - struct timeval time; - -/* Set to EV_FF_STATUS */ - unsigned short type; - -/* Contains the id of the effect */ - unsigned short code; - -/* Indicates the status */ - unsigned int value; -}; - -FF_STATUS_STOPPED The effect stopped playing -FF_STATUS_PLAYING The effect started to play - -NOTE: Status feedback is only supported by iforce driver. If you have - a really good reason to use this, please contact - linux-joystick@atrey.karlin.mff.cuni.cz or anssi.hannula@gmail.com - so that support for it can be added to the rest of the drivers. - |