diff options
author | Linus Torvalds <torvalds@g5.osdl.org> | 2006-10-02 11:20:33 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@g5.osdl.org> | 2006-10-02 11:20:33 -0400 |
commit | a12f66fccf2e266ad197df142b5ebafc6a169a8c (patch) | |
tree | 9d0bc76f8aa9c42fb44ce5f5bf6b4b09f4efafed /Documentation | |
parent | 12dce6263d43daeb4e16fa4eb964c1c99fa4fa2e (diff) | |
parent | bb0885900de49b5822d7e8c91c1adf9a0fcc228b (diff) |
Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input
* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input: (35 commits)
Input: wistron - add support for Acer TravelMate 2424NWXCi
Input: wistron - fix setting up special buttons
Input: add KEY_BLUETOOTH and KEY_WLAN definitions
Input: add new BUS_VIRTUAL bus type
Input: add driver for stowaway serial keyboards
Input: make input_register_handler() return error codes
Input: remove cruft that was needed for transition to sysfs
Input: fix input module refcounting
Input: constify input core
Input: libps2 - rearrange exports
Input: atkbd - support Microsoft Natural Elite Pro keyboards
Input: i8042 - disable MUX mode on Toshiba Equium A110
Input: i8042 - get rid of polling timer
Input: send key up events at disconnect
Input: constify psmouse driver
Input: i8042 - add Amoi to the MUX blacklist
Input: logips2pp - add sugnature 56 (Cordless MouseMan Wheel), cleanup
Input: add driver for Touchwin serial touchscreens
Input: add driver for Touchright serial touchscreens
Input: add driver for Penmount serial touchscreens
...
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/input/ff.txt | 112 |
1 files changed, 52 insertions, 60 deletions
diff --git a/Documentation/input/ff.txt b/Documentation/input/ff.txt index c7e10eaff20..c53b1c11aa4 100644 --- a/Documentation/input/ff.txt +++ b/Documentation/input/ff.txt | |||
@@ -1,67 +1,37 @@ | |||
1 | Force feedback for Linux. | 1 | Force feedback for Linux. |
2 | By Johann Deneux <deneux@ifrance.com> on 2001/04/22. | 2 | By Johann Deneux <deneux@ifrance.com> on 2001/04/22. |
3 | Updated by Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09. | ||
3 | You may redistribute this file. Please remember to include shape.fig and | 4 | You may redistribute this file. Please remember to include shape.fig and |
4 | interactive.fig as well. | 5 | interactive.fig as well. |
5 | ---------------------------------------------------------------------------- | 6 | ---------------------------------------------------------------------------- |
6 | 7 | ||
7 | 0. Introduction | 8 | 1. Introduction |
8 | ~~~~~~~~~~~~~~~ | 9 | ~~~~~~~~~~~~~~~ |
9 | This document describes how to use force feedback devices under Linux. The | 10 | This document describes how to use force feedback devices under Linux. The |
10 | goal is not to support these devices as if they were simple input-only devices | 11 | goal is not to support these devices as if they were simple input-only devices |
11 | (as it is already the case), but to really enable the rendering of force | 12 | (as it is already the case), but to really enable the rendering of force |
12 | effects. | 13 | effects. |
13 | At the moment, only I-Force devices are supported, and not officially. That | 14 | This document only describes the force feedback part of the Linux input |
14 | means I had to find out how the protocol works on my own. Of course, the | 15 | interface. Please read joystick.txt and input.txt before reading further this |
15 | information I managed to grasp is far from being complete, and I can not | 16 | document. |
16 | guarranty that this driver will work for you. | ||
17 | This document only describes the force feedback part of the driver for I-Force | ||
18 | devices. Please read joystick.txt before reading further this document. | ||
19 | 17 | ||
20 | 2. Instructions to the user | 18 | 2. Instructions to the user |
21 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 19 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
22 | Here are instructions on how to compile and use the driver. In fact, this | 20 | To enable force feedback, you have to: |
23 | driver is the normal iforce, input and evdev drivers written by Vojtech | 21 | |
24 | Pavlik, plus additions to support force feedback. | 22 | 1. have your kernel configured with evdev and a driver that supports your |
23 | device. | ||
24 | 2. make sure evdev module is loaded and /dev/input/event* device files are | ||
25 | created. | ||
25 | 26 | ||
26 | Before you start, let me WARN you that some devices shake violently during the | 27 | Before you start, let me WARN you that some devices shake violently during the |
27 | initialisation phase. This happens for example with my "AVB Top Shot Pegasus". | 28 | initialisation phase. This happens for example with my "AVB Top Shot Pegasus". |
28 | To stop this annoying behaviour, move you joystick to its limits. Anyway, you | 29 | To stop this annoying behaviour, move you joystick to its limits. Anyway, you |
29 | should keep a hand on your device, in order to avoid it to brake down if | 30 | should keep a hand on your device, in order to avoid it to break down if |
30 | something goes wrong. | 31 | something goes wrong. |
31 | 32 | ||
32 | At the kernel's compilation: | 33 | If you have a serial iforce device, you need to start inputattach. See |
33 | - Enable IForce/Serial | 34 | joystick.txt for details. |
34 | - Enable Event interface | ||
35 | |||
36 | Compile the modules, install them. | ||
37 | |||
38 | You also need inputattach. | ||
39 | |||
40 | You then need to insert the modules into the following order: | ||
41 | % modprobe joydev | ||
42 | % modprobe serport # Only for serial | ||
43 | % modprobe iforce | ||
44 | % modprobe evdev | ||
45 | % ./inputattach -ifor $2 & # Only for serial | ||
46 | If you are using USB, you don't need the inputattach step. | ||
47 | |||
48 | Please check that you have all the /dev/input entries needed: | ||
49 | cd /dev | ||
50 | rm js* | ||
51 | mkdir input | ||
52 | mknod input/js0 c 13 0 | ||
53 | mknod input/js1 c 13 1 | ||
54 | mknod input/js2 c 13 2 | ||
55 | mknod input/js3 c 13 3 | ||
56 | ln -s input/js0 js0 | ||
57 | ln -s input/js1 js1 | ||
58 | ln -s input/js2 js2 | ||
59 | ln -s input/js3 js3 | ||
60 | |||
61 | mknod input/event0 c 13 64 | ||
62 | mknod input/event1 c 13 65 | ||
63 | mknod input/event2 c 13 66 | ||
64 | mknod input/event3 c 13 67 | ||
65 | 35 | ||
66 | 2.1 Does it work ? | 36 | 2.1 Does it work ? |
67 | ~~~~~~~~~~~~~~~~~~ | 37 | ~~~~~~~~~~~~~~~~~~ |
@@ -70,9 +40,9 @@ There is an utility called fftest that will allow you to test the driver. | |||
70 | 40 | ||
71 | 3. Instructions to the developper | 41 | 3. Instructions to the developper |
72 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 42 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
73 | All interactions are done using the event API. That is, you can use ioctl() | 43 | All interactions are done using the event API. That is, you can use ioctl() |
74 | and write() on /dev/input/eventXX. | 44 | and write() on /dev/input/eventXX. |
75 | This information is subject to change. | 45 | This information is subject to change. |
76 | 46 | ||
77 | 3.1 Querying device capabilities | 47 | 3.1 Querying device capabilities |
78 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 48 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
@@ -86,18 +56,29 @@ int ioctl(int file_descriptor, int request, unsigned long *features); | |||
86 | 56 | ||
87 | Returns the features supported by the device. features is a bitfield with the | 57 | Returns the features supported by the device. features is a bitfield with the |
88 | following bits: | 58 | following bits: |
89 | - FF_X has an X axis (usually joysticks) | ||
90 | - FF_Y has an Y axis (usually joysticks) | ||
91 | - FF_WHEEL has a wheel (usually sterring wheels) | ||
92 | - FF_CONSTANT can render constant force effects | 59 | - FF_CONSTANT can render constant force effects |
93 | - FF_PERIODIC can render periodic effects (sine, triangle, square...) | 60 | - FF_PERIODIC can render periodic effects with the following waveforms: |
61 | - FF_SQUARE square waveform | ||
62 | - FF_TRIANGLE triangle waveform | ||
63 | - FF_SINE sine waveform | ||
64 | - FF_SAW_UP sawtooth up waveform | ||
65 | - FF_SAW_DOWN sawtooth down waveform | ||
66 | - FF_CUSTOM custom waveform | ||
94 | - FF_RAMP can render ramp effects | 67 | - FF_RAMP can render ramp effects |
95 | - FF_SPRING can simulate the presence of a spring | 68 | - FF_SPRING can simulate the presence of a spring |
96 | - FF_FRICTION can simulate friction | 69 | - FF_FRICTION can simulate friction |
97 | - FF_DAMPER can simulate damper effects | 70 | - FF_DAMPER can simulate damper effects |
98 | - FF_RUMBLE rumble effects (normally the only effect supported by rumble | 71 | - FF_RUMBLE rumble effects |
99 | pads) | ||
100 | - FF_INERTIA can simulate inertia | 72 | - FF_INERTIA can simulate inertia |
73 | - FF_GAIN gain is adjustable | ||
74 | - FF_AUTOCENTER autocenter is adjustable | ||
75 | |||
76 | Note: In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All | ||
77 | devices that support FF_RUMBLE support FF_PERIODIC (square, triangle, | ||
78 | sine) and the other way around. | ||
79 | |||
80 | Note: The exact syntax FF_CUSTOM is undefined for the time being as no driver | ||
81 | supports it yet. | ||
101 | 82 | ||
102 | 83 | ||
103 | int ioctl(int fd, EVIOCGEFFECTS, int *n); | 84 | int ioctl(int fd, EVIOCGEFFECTS, int *n); |
@@ -108,7 +89,7 @@ Returns the number of effects the device can keep in its memory. | |||
108 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 89 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
109 | #include <linux/input.h> | 90 | #include <linux/input.h> |
110 | #include <sys/ioctl.h> | 91 | #include <sys/ioctl.h> |
111 | 92 | ||
112 | int ioctl(int file_descriptor, int request, struct ff_effect *effect); | 93 | int ioctl(int file_descriptor, int request, struct ff_effect *effect); |
113 | 94 | ||
114 | "request" must be EVIOCSFF. | 95 | "request" must be EVIOCSFF. |
@@ -120,6 +101,9 @@ to the unique id assigned by the driver. This data is required for performing | |||
120 | some operations (removing an effect, controlling the playback). | 101 | some operations (removing an effect, controlling the playback). |
121 | This if field must be set to -1 by the user in order to tell the driver to | 102 | This if field must be set to -1 by the user in order to tell the driver to |
122 | allocate a new effect. | 103 | allocate a new effect. |
104 | |||
105 | Effects are file descriptor specific. | ||
106 | |||
123 | See <linux/input.h> for a description of the ff_effect struct. You should also | 107 | See <linux/input.h> for a description of the ff_effect struct. You should also |
124 | find help in a few sketches, contained in files shape.fig and interactive.fig. | 108 | find help in a few sketches, contained in files shape.fig and interactive.fig. |
125 | You need xfig to visualize these files. | 109 | You need xfig to visualize these files. |
@@ -128,8 +112,8 @@ You need xfig to visualize these files. | |||
128 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 112 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
129 | int ioctl(int fd, EVIOCRMFF, effect.id); | 113 | int ioctl(int fd, EVIOCRMFF, effect.id); |
130 | 114 | ||
131 | This makes room for new effects in the device's memory. Please note this won't | 115 | This makes room for new effects in the device's memory. Note that this also |
132 | stop the effect if it was playing. | 116 | stops the effect if it was playing. |
133 | 117 | ||
134 | 3.4 Controlling the playback of effects | 118 | 3.4 Controlling the playback of effects |
135 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 119 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
@@ -149,22 +133,21 @@ Control of playing is done with write(). Below is an example: | |||
149 | play.type = EV_FF; | 133 | play.type = EV_FF; |
150 | play.code = effect.id; | 134 | play.code = effect.id; |
151 | play.value = 3; | 135 | play.value = 3; |
152 | 136 | ||
153 | write(fd, (const void*) &play, sizeof(play)); | 137 | write(fd, (const void*) &play, sizeof(play)); |
154 | ... | 138 | ... |
155 | /* Stop an effect */ | 139 | /* Stop an effect */ |
156 | stop.type = EV_FF; | 140 | stop.type = EV_FF; |
157 | stop.code = effect.id; | 141 | stop.code = effect.id; |
158 | stop.value = 0; | 142 | stop.value = 0; |
159 | 143 | ||
160 | write(fd, (const void*) &play, sizeof(stop)); | 144 | write(fd, (const void*) &play, sizeof(stop)); |
161 | 145 | ||
162 | 3.5 Setting the gain | 146 | 3.5 Setting the gain |
163 | ~~~~~~~~~~~~~~~~~~~~ | 147 | ~~~~~~~~~~~~~~~~~~~~ |
164 | Not all devices have the same strength. Therefore, users should set a gain | 148 | Not all devices have the same strength. Therefore, users should set a gain |
165 | factor depending on how strong they want effects to be. This setting is | 149 | factor depending on how strong they want effects to be. This setting is |
166 | persistent across access to the driver, so you should not care about it if | 150 | persistent across access to the driver. |
167 | you are writing games, as another utility probably already set this for you. | ||
168 | 151 | ||
169 | /* Set the gain of the device | 152 | /* Set the gain of the device |
170 | int gain; /* between 0 and 100 */ | 153 | int gain; /* between 0 and 100 */ |
@@ -204,11 +187,14 @@ type of device, not all parameters can be dynamically updated. For example, | |||
204 | the direction of an effect cannot be updated with iforce devices. In this | 187 | the direction of an effect cannot be updated with iforce devices. In this |
205 | case, the driver stops the effect, up-load it, and restart it. | 188 | case, the driver stops the effect, up-load it, and restart it. |
206 | 189 | ||
190 | Therefore it is recommended to dynamically change direction while the effect | ||
191 | is playing only when it is ok to restart the effect with a replay count of 1. | ||
207 | 192 | ||
208 | 3.8 Information about the status of effects | 193 | 3.8 Information about the status of effects |
209 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 194 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
210 | Every time the status of an effect is changed, an event is sent. The values | 195 | Every time the status of an effect is changed, an event is sent. The values |
211 | and meanings of the fields of the event are as follows: | 196 | and meanings of the fields of the event are as follows: |
197 | |||
212 | struct input_event { | 198 | struct input_event { |
213 | /* When the status of the effect changed */ | 199 | /* When the status of the effect changed */ |
214 | struct timeval time; | 200 | struct timeval time; |
@@ -225,3 +211,9 @@ struct input_event { | |||
225 | 211 | ||
226 | FF_STATUS_STOPPED The effect stopped playing | 212 | FF_STATUS_STOPPED The effect stopped playing |
227 | FF_STATUS_PLAYING The effect started to play | 213 | FF_STATUS_PLAYING The effect started to play |
214 | |||
215 | NOTE: Status feedback is only supported by iforce driver. If you have | ||
216 | a really good reason to use this, please contact | ||
217 | linux-joystick@atrey.karlin.mff.cuni.cz or anssi.hannula@gmail.com | ||
218 | so that support for it can be added to the rest of the drivers. | ||
219 | |||