~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/input/joydev/joystick-api.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/input/joydev/joystick-api.rst (Version linux-6.12-rc7) and /Documentation/input/joydev/joystick-api.rst (Version linux-4.4.302)


  1 .. _joystick-api:                                 
  2                                                   
  3 =====================                             
  4 Programming Interface                             
  5 =====================                             
  6                                                   
  7 :Author: Ragnar Hojland Espinosa <ragnar@macula    
  8                                                   
  9 Introduction                                      
 10 ============                                      
 11                                                   
 12 .. important::                                    
 13    This document describes legacy ``js`` inter    
 14    encouraged to switch to the generic event (    
 15                                                   
 16 The 1.0 driver uses a new, event based approac    
 17 Instead of the user program polling for the jo    
 18 driver now reports only any changes of its sta    
 19 joystick.h and jstest.c included in the joysti    
 20 information. The joystick device can be used i    
 21 nonblocking mode, and supports select() calls.    
 22                                                   
 23 For backward compatibility the old (v0.x) inte    
 24 Any call to the joystick driver using the old     
 25 that are compatible to the old interface. This    
 26 to 2 axes, and applications using it usually d    
 27 the driver provides up to 32.                     
 28                                                   
 29 Initialization                                    
 30 ==============                                    
 31                                                   
 32 Open the joystick device following the usual s    
 33 Since the driver now reports events instead of    
 34 immediately after the open it will issue a ser    
 35 (JS_EVENT_INIT) that you can read to obtain th    
 36 joystick.                                         
 37                                                   
 38 By default, the device is opened in blocking m    
 39                                                   
 40         int fd = open ("/dev/input/js0", O_RDO    
 41                                                   
 42                                                   
 43 Event Reading                                     
 44 =============                                     
 45                                                   
 46 ::                                                
 47                                                   
 48         struct js_event e;                        
 49         read (fd, &e, sizeof(e));                 
 50                                                   
 51 where js_event is defined as::                    
 52                                                   
 53         struct js_event {                         
 54                 __u32 time;     /* event times    
 55                 __s16 value;    /* value */       
 56                 __u8 type;      /* event type     
 57                 __u8 number;    /* axis/button    
 58         };                                        
 59                                                   
 60 If the read is successful, it will return size    
 61 more than one event per read as described in s    
 62                                                   
 63                                                   
 64 js_event.type                                     
 65 -------------                                     
 66                                                   
 67 The possible values of ``type`` are::             
 68                                                   
 69         #define JS_EVENT_BUTTON         0x01      
 70         #define JS_EVENT_AXIS           0x02      
 71         #define JS_EVENT_INIT           0x80      
 72                                                   
 73 As mentioned above, the driver will issue synt    
 74 events on open. That is, if it's issuing an IN    
 75 current type value will be::                      
 76                                                   
 77         int type = JS_EVENT_BUTTON | JS_EVENT_    
 78                                                   
 79 If you choose not to differentiate between syn    
 80 you can turn off the JS_EVENT_INIT bits::         
 81                                                   
 82         type &= ~JS_EVENT_INIT;                   
 83                                                   
 84                                                   
 85 js_event.number                                   
 86 ---------------                                   
 87                                                   
 88 The values of ``number`` correspond to the axi    
 89 generated the event. Note that they carry sepa    
 90 is, you have both an axis 0 and a button 0). G    
 91                                                   
 92         =============== =======                   
 93         Axis            number                    
 94         =============== =======                   
 95         1st Axis X      0                         
 96         1st Axis Y      1                         
 97         2nd Axis X      2                         
 98         2nd Axis Y      3                         
 99         ...and so on                              
100         =============== =======                   
101                                                   
102 Hats vary from one joystick type to another. S    
103 directions, some only in 4. The driver, howeve    
104 independent axes, even if the hardware doesn't    
105                                                   
106                                                   
107 js_event.value                                    
108 --------------                                    
109                                                   
110 For an axis, ``value`` is a signed integer bet    
111 representing the position of the joystick alon    
112 don't read a 0 when the joystick is ``dead``,     
113 full range, you should recalibrate it (with, f    
114                                                   
115 For a button, ``value`` for a press button eve    
116 button event is 0.                                
117                                                   
118 Though this::                                     
119                                                   
120         if (js_event.type == JS_EVENT_BUTTON)     
121                 buttons_state ^= (1 << js_even    
122         }                                         
123                                                   
124 may work well if you handle JS_EVENT_INIT even    
125                                                   
126 ::                                                
127                                                   
128         if ((js_event.type & ~JS_EVENT_INIT) =    
129                 if (js_event.value)               
130                         buttons_state |= (1 <<    
131                 else                              
132                         buttons_state &= ~(1 <    
133         }                                         
134                                                   
135 is much safer since it can't lose sync with th    
136 have to write a separate handler for JS_EVENT_    
137 snippet, this ends up being shorter.              
138                                                   
139                                                   
140 js_event.time                                     
141 -------------                                     
142                                                   
143 The time an event was generated is stored in `    
144 in milliseconds since ... well, since sometime    
145 task of detecting double clicks, figuring out     
146 presses happened at the same time, and similar    
147                                                   
148                                                   
149 Reading                                           
150 =======                                           
151                                                   
152 If you open the device in blocking mode, a rea    
153 wait) forever until an event is generated and     
154 are two alternatives if you can't afford to wa    
155 admittedly, a long time;)                         
156                                                   
157         a) use select to wait until there's da    
158            until it timeouts. There's a good e    
159            man page.                              
160                                                   
161         b) open the device in non-blocking mod    
162                                                   
163                                                   
164 O_NONBLOCK                                        
165 ----------                                        
166                                                   
167 If read returns -1 when reading in O_NONBLOCK     
168 necessarily a "real" error (check errno(3)); i    
169 are no events pending to be read on the driver    
170 all events on the queue (that is, until you ge    
171                                                   
172 For example,                                      
173                                                   
174 ::                                                
175                                                   
176         while (1) {                               
177                 while (read (fd, &e, sizeof(e)    
178                         process_event (e);        
179                 }                                 
180                 /* EAGAIN is returned when the    
181                 if (errno != EAGAIN) {            
182                         /* error */               
183                 }                                 
184                 /* do something interesting wi    
185         }                                         
186                                                   
187 One reason for emptying the queue is that if i    
188 missing events since the queue is finite, and     
189 overwritten.                                      
190                                                   
191 The other reason is that you want to know all     
192 delay the processing till later.                  
193                                                   
194 Why can the queue get full? Because you don't     
195 mentioned, or because too much time elapses fr    
196 and too many events to store in the queue get     
197 high system load may contribute to space those    
198                                                   
199 If time between reads is enough to fill the qu    
200 the driver will switch to startup mode and nex    
201 synthetic events (JS_EVENT_INIT) will be gener    
202 the actual state of the joystick.                 
203                                                   
204                                                   
205 .. note::                                         
206                                                   
207  As of version 1.2.8, the queue is circular an    
208  events. You can increment this size bumping u    
209  joystick.h and recompiling the driver.           
210                                                   
211                                                   
212 In the above code, you might as well want to r    
213 at a time using the typical read(2) functional    
214 replace the read above with something like::      
215                                                   
216         struct js_event mybuffer[0xff];           
217         int i = read (fd, mybuffer, sizeof(myb    
218                                                   
219 In this case, read would return -1 if the queu    
220 other value in which the number of events read    
221 sizeof(js_event)  Again, if the buffer was ful    
222 process the events and keep reading it until y    
223                                                   
224                                                   
225 IOCTLs                                            
226 ======                                            
227                                                   
228 The joystick driver defines the following ioct    
229                                                   
230                                 /* function       
231         #define JSIOCGAXES      /* get number     
232         #define JSIOCGBUTTONS   /* get number     
233         #define JSIOCGVERSION   /* get driver     
234         #define JSIOCGNAME(len) /* get identif    
235         #define JSIOCSCORR      /* set correct    
236         #define JSIOCGCORR      /* get correct    
237                                                   
238 For example, to read the number of axes::         
239                                                   
240         char number_of_axes;                      
241         ioctl (fd, JSIOCGAXES, &number_of_axes    
242                                                   
243                                                   
244 JSIOGCVERSION                                     
245 -------------                                     
246                                                   
247 JSIOGCVERSION is a good way to check in run-ti    
248 driver is 1.0+ and supports the event interfac    
249 IOCTL will fail. For a compile-time decision,     
250 JS_VERSION symbol::                               
251                                                   
252         #ifdef JS_VERSION                         
253         #if JS_VERSION > 0xsomething              
254                                                   
255                                                   
256 JSIOCGNAME                                        
257 ----------                                        
258                                                   
259 JSIOCGNAME(len) allows you to get the name str    
260 as is being printed at boot time. The 'len' ar    
261 buffer provided by the application asking for     
262 possible overrun should the name be too long::    
263                                                   
264         char name[128];                           
265         if (ioctl(fd, JSIOCGNAME(sizeof(name))    
266                 strscpy(name, "Unknown", sizeo    
267         printf("Name: %s\n", name);               
268                                                   
269                                                   
270 JSIOC[SG]CORR                                     
271 -------------                                     
272                                                   
273 For usage on JSIOC[SG]CORR I suggest you to lo    
274 not needed in a normal program, only in joysti    
275 such as jscal or kcmjoy. These IOCTLs and data    
276 to be in the stable part of the API, and there    
277 warning in following releases of the driver.      
278                                                   
279 Both JSIOCSCORR and JSIOCGCORR expect &js_corr    
280 information for all axes. That is, struct js_c    
281                                                   
282 struct js_corr is defined as::                    
283                                                   
284         struct js_corr {                          
285                 __s32 coef[8];                    
286                 __u16 prec;                       
287                 __u16 type;                       
288         };                                        
289                                                   
290 and ``type``::                                    
291                                                   
292         #define JS_CORR_NONE            0x00      
293         #define JS_CORR_BROKEN          0x01      
294                                                   
295                                                   
296 Backward compatibility                            
297 ======================                            
298                                                   
299 The 0.x joystick driver API is quite limited a    
300 The driver offers backward compatibility, thou    
301                                                   
302         struct JS_DATA_TYPE js;                   
303         while (1) {                               
304                 if (read (fd, &js, JS_RETURN)     
305                         /* error */               
306                 }                                 
307                 usleep (1000);                    
308         }                                         
309                                                   
310 As you can figure out from the example, the re    
311 with the actual state of the joystick::           
312                                                   
313         struct JS_DATA_TYPE {                     
314                 int buttons;    /* immediate b    
315                 int x;          /* immediate x    
316                 int y;          /* immediate y    
317         };                                        
318                                                   
319 and JS_RETURN is defined as::                     
320                                                   
321         #define JS_RETURN       sizeof(struct     
322                                                   
323 To test the state of the buttons,                 
324                                                   
325 ::                                                
326                                                   
327         first_button_state  = js.buttons & 1;     
328         second_button_state = js.buttons & 2;     
329                                                   
330 The axis values do not have a defined range in    
331 except that the values are non-negative. The 1    
332 fixed range for reporting the values, 1 being     
333 center, and 255 maximum value.                    
334                                                   
335 The v0.8.0.2 driver also had an interface for     
336 called Multisystem joysticks in this driver),     
337 doesn't try to be compatible with that interfa    
338                                                   
339                                                   
340 Final Notes                                       
341 ===========                                       
342                                                   
343 ::                                                
344                                                   
345   ____/|        Comments, additions, and speci    
346   \ o.O|        Documentation valid for at lea    
347    =(_)=        driver and as usual, the ultim    
348      U          to "Use The Source Luke" or, a    
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php