1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]> 2 3<book id="MouseGuide"> 4 <bookinfo> 5 <title>Mouse Drivers</title> 6 7 <authorgroup> 8 <author> 9 <firstname>Alan</firstname> 10 <surname>Cox</surname> 11 <affiliation> 12 <address> 13 <email>alan@redhat.com</email> 14 </address> 15 </affiliation> 16 </author> 17 </authorgroup> 18 19 <copyright> 20 <year>2000</year> 21 <holder>Alan Cox</holder> 22 </copyright> 23 24 <legalnotice> 25 <para> 26 This documentation is free software; you can redistribute 27 it and/or modify it under the terms of the GNU General Public 28 License as published by the Free Software Foundation; either 29 version 2 of the License, or (at your option) any later 30 version. 31 </para> 32 33 <para> 34 This program is distributed in the hope that it will be 35 useful, but WITHOUT ANY WARRANTY; without even the implied 36 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 37 See the GNU General Public License for more details. 38 </para> 39 40 <para> 41 You should have received a copy of the GNU General Public 42 License along with this program; if not, write to the Free 43 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 44 MA 02111-1307 USA 45 </para> 46 47 <para> 48 For more details see the file COPYING in the source 49 distribution of Linux. 50 </para> 51 </legalnotice> 52 </bookinfo> 53 54 <toc></toc> 55 56 <chapter id="intro"> 57 <title>Introduction</title> 58 <note> 59 <title>Earlier publication</title> 60 <para> 61 Parts of this document first appeared in Linux Magazine under a 62 ninety day exclusivity. 63 </para> 64 </note> 65 66 <para> 67 Mice are conceptually one of the simplest device interfaces in the 68 Linux operating system. Not all mice are handled by the kernel. 69 Instead there is a two layer abstraction. 70 </para> 71 72 <para> 73 The kernel mouse drivers and userspace drivers for the serial mice are 74 all managed by a system daemon called <application>gpm</application> 75 - the general purpose mouse driver. <application>gpm</application> 76 handles cutting and pasting on the text consoles. It provides a 77 general library for mouse-aware applications and it handles the 78 sharing of mouse services with the 79 <application>X Window System</application> user interface. 80 </para> 81 <para> 82 Sometimes a mouse speaks a sufficiently convoluted protocol that the 83 protocol is handled by <application>Gpm</application> itself. Most 84 of the mouse drivers follow a common interface called the bus mouse 85 protocol. 86 </para> 87 <para> 88 Each read from a bus mouse interface device returns a block of data. 89 The first three bytes of each read are defined as follows: 90 91 <table frame=all> 92 <title>Mouse Data Encoding</title> 93 <tgroup cols=2 align=left> 94 <tbody> 95 <row> 96 <entry>Byte 0</entry> 97 <entry>0x80 + the buttons currently down.</entry> 98 </row> 99 <row> 100 <entry>Byte 1</entry> 101 <entry>A signed value for the shift in X position</entry> 102 </row> 103 <row> 104 <entry>Byte 2</entry> 105 <entry>A signed value for the shift in Y position</entry> 106 </row> 107 </tbody> 108 </tgroup> 109 </table> 110 111 An application can choose to read more than 3 bytes. The rest of the 112 bytes will be zero, or may optionally return some additional 113 device-specific information. 114 </para> 115 <para> 116 The position values are truncated if they exceed the 8bit range (that 117 is -127 <= delta <= 127). While the value -128 does fit into a 118 byte is not allowed. 119 </para> 120 <para> 121 The <mousebutton>buttons</mousebutton> are numbered left to right as 122 0, 1, 2, 3.. and each button sets the relevant bit. So a user pressing 123 the left and right button of a three button mouse will set bits 0 and 2. 124 </para> 125 <para> 126 All mice are required to support the <function>poll</function> 127 operation. Indeed pretty much every user of a mouse device uses 128 <function>poll</function> to wait for mouse events to occur. 129 </para> 130 <para> 131 Finally the mice support asynchronous I/O. This is a topic we have not 132 yet covered but which I will explain after looking at a simple mouse 133 driver. 134 </para> 135 </chapter> 136 137 <chapter id="driver"> 138 <title>A simple mouse driver</title> 139 <para> 140 First we will need the set up functions for our mouse device. To keep 141 this simple our imaginary mouse device has three I/O ports fixed at I/O 142 address 0x300 and always lives on interrupt 5. The ports will be the X 143 position, the Y position and the buttons in that order. 144 </para> 145 146 <programlisting> 147#define OURMOUSE_BASE 0x300 148 149static struct miscdevice our_mouse = { 150 OURMOUSE_MINOR, "ourmouse", &our_mouse_fops 151}; 152 153__init ourmouse_init(void) 154{ 155 156 if (request_region(OURMOUSE_BASE, 3, "ourmouse") < 0) { 157 printk(KERN_ERR "ourmouse: request_region failed.\n"); 158 return -ENODEV; 159 } 160 161 if (misc_register(&our_mouse) < 0) { 162 printk(KERN_ERR "ourmouse: cannot register misc device.\n"); 163 release_region(OURMOUSE_BASE, 3); 164 return -EBUSY; 165 } 166 167 return 0; 168} 169 </programlisting> 170 171 <para> 172 The <structname>miscdevice</structname> is new here. Linux normally 173 parcels devices out by major number, and each device has 256 units. 174 For things like mice this is extremely wasteful so a device exists 175 which is used to accumulate all the odd individual devices that 176 computers tend to have. 177 </para> 178 <para> 179 Minor numbers in this space are allocated by a central source, although 180 you can look in the kernel <filename>Documentation/devices.txt</filename> 181 file and pick a free one for development use. This kernel file also 182 carries instructions for registering a device. This may change over time 183 so it is a good idea to obtain a current copy of this file first. 184 </para> 185 <para> 186 Our code then is fairly simple. We reserve our I/O address space with 187 request_region, checking to make sure that it succeeded (i.e. the 188 space wasn't reserved by anyone else). 189 </para> 190 <para> 191 Then we ask the misc driver to allocate our minor device number. We also 192 hand it our name (which is used in 193 <filename class="directory">/proc/misc</filename>) and a set of file 194 operations that are to be used. The file operations work exactly like the 195 file operations you would register for a normal character device. The misc 196 device itself is simply acting as a redirector for requests. 197 Since misc_register can fail, it is important to check for failure 198 and act accordingly (which in the case of a mouse driver is to abort, 199 since you can't use the mouse without a working device node). 200 </para> 201 <para> 202 Next, in order to be able to use and test our code we need to add some 203 module code to support it. This too is fairly simple: 204 </para> 205 <programlisting> 206#ifdef MODULE 207 208int init_module(void) 209{ 210 if(ourmouse_init()<0) 211 return -ENODEV: 212 return 0; 213} 214 215void cleanup_module(void) 216{ 217 misc_deregister(&our_mouse); 218 free_region(OURMOUSE_BASE, 3); 219} 220 221 222#endif 223 </programlisting> 224 225 <para> 226 The module code provides the normal two functions. The 227 <function>init_module</function> function is called when the module is 228 loaded. In our case it simply calls the initialising function we wrote 229 and returns an error if this fails. This ensures the module will only 230 be loaded if it was successfully set up. 231 </para> 232 <para> 233 The <function>cleanup_module</function> function is called when the 234 module is unloaded. We give the miscellaneous device entry back, and 235 then free our I/O resources. If we didn't free the I/O resources then 236 the next time the module loaded it would think someone else had its I/O 237 space. 238 </para> 239 <para> 240 Once the <function>misc_deregister</function> has been called any 241 attempts to open the mouse device will fail with the error 242 <errorcode>ENODEV</errorcode> (<errorname>No such device</errorname>). 243 </para> 244 <para> 245 Next we need to fill in our file operations. A mouse doesn't need many 246 of these. We need to provide open, release, read and poll. That makes 247 for a nice simple structure: 248 </para> 249 250 <programlisting> 251struct file_operations our_mouse_fops = { 252 owner: THIS_MODULE, /* Automatic usage management */ 253 read: read_mouse, /* You can read a mouse */ 254 write: write_mouse, /* This won't do a lot */ 255 poll: poll_mouse, /* Poll */ 256 open: open_mouse, /* Called on open */ 257 release: close_mouse, /* Called on close */ 258}; 259 </programlisting> 260 261 <para> 262 There is nothing particularly special needed here. We provide functions 263 for all the relevant or required operations and little else. There is 264 nothing stopping us providing an ioctl function for this mouse. Indeed 265 if you have a configurable mouse it may be very appropriate to provide 266 configuration interfaces via ioctl calls. 267 </para> 268 <para> 269 The syntax we use is not standard C as such. GCC provides the ability 270 to initialise fields by name, and this generally makes the method table 271 much easier to read than counting through NULL pointers and remembering 272 the order by hand. 273 </para> 274 <para> 275 The owner field is used to manage the locking of module load an 276 unloading. It is obviously important that a module is not unloaded while 277 in use. When your device is opened the module specified by "owner" is 278 locked. When it is finally released the module is unlocked. 279 </para> 280 <para> 281 The open and close routines need to manage enabling and disabling the 282 interrupts for the mouse as well as stopping the mouse being unloaded 283 when it is no longer required. 284 </para> 285 286 <programlisting> 287static int mouse_users = 0; /* User count */ 288static int mouse_dx = 0; /* Position changes */ 289static int mouse_dy = 0; 290static int mouse_event = 0; /* Mouse has moved */ 291 292static int open_mouse(struct inode *inode, struct file *file) 293{ 294 if(mouse_users++) 295 return 0; 296 297 if(request_irq(mouse_intr, OURMOUSE_IRQ, 0, "ourmouse", NULL)) 298 { 299 mouse_users--; 300 return -EBUSY; 301 } 302 mouse_dx = 0; 303 mouse_dy = 0; 304 mouse_event = 0; 305 mouse_buttons = 0; 306 return 0; 307} 308 </programlisting> 309 <para> 310 The open function has to do a small amount of housework. We keep a count 311 of the number of times the mouse is open. This is because we do not want 312 to request the interrupt multiple times. If the mouse has at least one 313 user then it is set up and we simply add to the user count and return 314 <returnvalue>0</returnvalue> for success. 315 </para> 316 <para> 317 We grab the interrupt and thus start mouse interrupts. If the interrupt 318 has been borrowed by some other driver then <function>request_irq</function> 319 will fail and we will return an error. If we were capable of sharing an 320 interrupt line we would specify <constant>SA_SHIRQ</constant> instead of 321 <constant>zero</constant>. Provided that everyone claiming an interrupt 322 sets this flag, they get to share the line. <hardware>PCI</hardware> can 323 share interrupts, <hardware>ISA</hardware> normally however cannot. 324 </para> 325 <para> 326 We do the housekeeping. We make the current mouse position the starting 327 point for accumulated changes and declare that nothing has happened 328 since the mouse driver was opened. 329 </para> 330 <para> 331 The release function needs to unwind all these: 332 </para> 333 <programlisting> 334static int close_mouse(struct inode *inode, struct file *file) 335{ 336 if(--mouse_users) 337 return 0; 338 free_irq(OURMOUSE_IRQ, NULL); 339 return 0; 340} 341 </programlisting> 342 <para> 343 We count off a user and provided that there are still other users need 344 take no further action. The last person closing the mouse causes us to 345 free up the interrupt. This stops interrupts from the mouse from using 346 our CPU time, and ensures that the mouse can now be unloaded. 347 </para> 348 <para> 349 We can fill in the write handler at this point as the write function for 350 our mouse simply declines to allow writes: 351 </para> 352 353 <programlisting> 354static ssize_t write_mouse(struct file *file, const char *buffer, size_t 355 count, loff_t *ppos) 356{ 357 return -EINVAL; 358} 359 </programlisting> 360 361 <para> 362 This is pretty much self-explanatory. Whenever you write you get told 363 it was an invalid function. 364 </para> 365 <para> 366 To make the poll and read functions work we have to consider how we 367 handle the mouse interrupt. 368 </para> 369 370 <programlisting> 371static struct wait_queue *mouse_wait; 372static spinlock_t mouse_lock = SPIN_LOCK_UNLOCKED; 373 374static void ourmouse_interrupt(int irq, void *dev_id, struct pt_regs *regs) 375{ 376 char delta_x; 377 char delta_y; 378 unsigned char new_buttons; 379 380 delta_x = inb(OURMOUSE_BASE); 381 delta_y = inb(OURMOUSE_BASE+1); 382 new_buttons = inb(OURMOUSE_BASE+2); 383 384 if(delta_x || delta_y || new_buttons != mouse_buttons) 385 { 386 /* Something happened */ 387 388 spin_lock(&mouse_lock); 389 mouse_event = 1; 390 mouse_dx += delta_x; 391 mouse_dy += delta_y; 392 mouse_buttons = new_buttons; 393 spin_unlock(&mouse_lock); 394 395 wake_up_interruptible(&mouse_wait); 396 } 397} 398 </programlisting> 399 400 <para> 401 The interrupt handler reads the mouse status. The next thing we do is 402 to check whether something has changed. If the mouse was smart it would 403 only interrupt us if something had changed, but let's assume our mouse 404 is stupid as most mice actually tend to be. 405 </para> 406 <para> 407 If the mouse has changed we need to update the status variables. What we 408 don't want is the mouse functions reading these variables to read them 409 during a change. We add a spinlock that protects these variables while we 410 play with them. 411 </para> 412 <para> 413 If a change has occurred we also need to wake sleeping processes, so we 414 add a wakeup call and a <structname>wait_queue</structname> to use when 415 we wish to await a mouse event. 416 </para> 417 <para> 418 Now we have the wait queue we can implement the poll function for the 419 mouse relatively easily: 420 </para> 421 422 <programlisting> 423static unsigned int mouse_poll(struct file *file, poll_table *wait) 424{ 425 poll_wait(file, &mouse_wait, wait); 426 if(mouse_event) 427 return POLLIN | POLLRDNORM; 428 return 0; 429} 430 </programlisting> 431 432 <para> 433 This is fairly standard poll code. First we add the wait queue to the 434 list of queues we want to monitor for an event. Secondly we check if an 435 event has occurred. We only have one kind of event - the 436 <varname>mouse_event</varname> flag tells us that something happened. 437 We know that this something can only be mouse data. We return the flags 438 indicating input and normal reading will succeed. 439 </para> 440 <para> 441 You may be wondering what happens if the function returns saying 'no 442 event yet'. In this case the wake up from the wait queue we added to 443 the poll table will cause the function to be called again. Eventually 444 we will be woken up and have an event ready. At this point the 445 <function>poll</function> call will exit back to the user. 446 </para> 447 <para> 448 After the poll completes the user will want to read the data. We now 449 need to think about how our <function>mouse_read</function> function 450 will work: 451 </para> 452 <programlisting> 453static ssize_t mouse_read(struct file *file, char *buffer, 454 size_t count, loff_t *pos) 455{ 456 int dx, dy; 457 unsigned char button; 458 unsigned long flags; 459 int n; 460 461 if(count<3) 462 return -EINVAL; 463 464 /* 465 * Wait for an event 466 */ 467 468 while(!mouse_event) 469 { 470 if(file->f_flags&O_NDELAY) 471 return -EAGAIN; 472 interruptible_sleep_on(&mouse_wait); 473 if(signal_pending(current)) 474 return -ERESTARTSYS; 475 } 476 </programlisting> 477 478 <para> 479 We start by validating that the user is reading enough data. We could 480 handle partial reads if we wanted but it isn't terribly useful and the 481 mouse drivers don't bother to try. 482 </para> 483 <para> 484 Next we wait for an event to occur. The loop is fairly standard event 485 waiting in Linux. Having checked that the event has not yet occurred, we 486 then check if an event is pending and if not we need to sleep. 487 </para> 488 <para> 489 A user process can set the <constant>O_NDELAY</constant> flag on a file 490 to indicate that it wishes to be told immediately if no event is 491 pending. We check this and give the appropriate error if so. 492 </para> 493 <para> 494 Next we sleep until the mouse or a signal awakens us. A signal will 495 awaken us as we have used <function>wakeup_interruptible</function>. 496 This is important as it means a user can kill processes waiting for 497 the mouse - clearly a desirable property. If we are interrupted we 498 exit the call and the kernel will then process signals and maybe 499 restart the call again - from the beginning. 500 </para> 501 <para> 502 This code contains a classic Linux bug. All will be revealed later in this 503 article as well as explanations for how to avoid it. 504 </para> 505 <programlisting> 506 /* Grab the event */ 507 508 spinlock_irqsave(&mouse_lock, flags); 509 510 dx = mouse_dx; 511 dy = mouse_dy; 512 button = mouse_buttons; 513 514 if(dx<=-127) 515 dx=-127; 516 if(dx>=127) 517 dx=127; 518 if(dy<=-127) 519 dy=-127; 520 if(dy>=127) 521 dy=127; 522 523 mouse_dx -= dx; 524 mouse_dy -= dy; 525 526 if(mouse_dx == 0 && mouse_dy == 0) 527 mouse_event = 0; 528 529 spin_unlock_irqrestore(&mouse_lock, flags); 530 </programlisting> 531 <para> 532 This is the next stage. Having established that there is an event 533 going, we capture it. To be sure that the event is not being updated 534 as we capture it we also take the spinlock and thus prevent parallel 535 updates. Note here we use <function>spinlock_irqsave</function>. We 536 need to disable interrupts on the local processor otherwise bad things 537 will happen. 538 </para> 539 <para> 540 What will occur is that we take the spinlock. While we hold the lock 541 an interrupt will occur. At this point our interrupt handler will try 542 and take the spinlock. It will sit in a loop waiting for the read 543 routine to release the lock. However because we are sitting in a loop 544 in the interrupt handler we will never release the lock. The machine 545 hangs and the user gets upset. 546 </para> 547 <para> 548 By blocking the interrupt on this processor we ensure that the lock 549 holder will always give the lock back without deadlocking. 550 </para> 551 <para> 552 There is a little cleverness in the reporting mechanism too. We can 553 only report a move of 127 per read. We don't however want to lose 554 information by throwing away further movement. Instead we keep 555 returning as much information as possible. Each time we return a 556 report we remove the amount from the pending movement in 557 <varname>mouse_dx</varname> and <varname>mouse_dy</varname>. Eventually 558 when these counts hit zero we clear the <varname>mouse_event</varname> 559 flag as there is nothing else left to report. 560 </para> 561 562 <programlisting> 563 if(put_user(button|0x80, buffer)) 564 return -EFAULT; 565 if(put_user((char)dx, buffer+1)) 566 return -EFAULT; 567 if(put_user((char)dy, buffer+2)) 568 return -EFAULT; 569 570 for(n=3; n < count; n++) 571 if(put_user(0x00, buffer+n)) 572 return -EFAULT; 573 574 return count; 575} 576 </programlisting> 577 578 <para> 579 Finally we must put the results in the user supplied buffer. We cannot 580 do this while holding the lock as a write to user memory may sleep. 581 For example the user memory may be residing on disk at this instant. 582 Thus we did our computation beforehand and now copy the data. Each 583 <function>put_user call</function> is filling in one byte of the buffer. 584 If it returns an error we inform the program that it passed us an 585 invalid buffer and abort. 586 </para> 587 <para> 588 Having written the data we blank the rest of the buffer that was read 589 and report the read as being successful. 590 </para> 591 </chapter> 592 593 <chapter id="debugging"> 594 <title>Debugging the mouse driver</title> 595 596 <para> 597 We now have an almost perfectly usable mouse driver. If you were to 598 actually try and use it however you would eventually find a couple of 599 problems with it. A few programs will also not work with as it does not 600 yet support asynchronous I/O. 601 </para> 602 <para> 603 First let us look at the bugs. The most obvious one isn't really a driver 604 bug but a failure to consider the consequences. Imagine you bumped the 605 mouse hard by accident and sent it skittering across the desk. The mouse 606 interrupt routine will add up all that movement and report it in steps of 607 127 until it has reported all of it. Clearly there is a point beyond 608 which mouse movement isn't worth reporting. We need to add this as a 609 limit to the interrupt handler: 610 </para> 611 612 <programlisting> 613static void ourmouse_interrupt(int irq, void *dev_id, struct pt_regs *regs) 614{ 615 char delta_x; 616 char delta_y; 617 unsigned char new_buttons; 618 619 delta_x = inb(OURMOUSE_BASE); 620 delta_y = inb(OURMOUSE_BASE+1); 621 new_buttons = inb(OURMOUSE_BASE+2); 622 623 if(delta_x || delta_y || new_buttons != mouse_buttons) 624 { 625 /* Something happened */ 626 627 spin_lock(&mouse_lock); 628 mouse_event = 1; 629 mouse_dx += delta_x; 630 mouse_dy += delta_y; 631 632 if(mouse_dx < -4096) 633 mouse_dx = -4096; 634 if(mouse_dx > 4096) 635 mouse_dx = 4096; 636 637 if(mouse_dy < -4096) 638 mouse_dy = -4096; 639 if(mouse_dy > 4096) 640 mouse_dy = 4096; 641 642 mouse_buttons = new_buttons; 643 spin_unlock(&mouse_lock); 644 645 wake_up_interruptible(&mouse_wait); 646 } 647} 648 </programlisting> 649 650 <para> 651 By adding these checks we limit the range of accumulated movement to 652 something sensible. 653 </para> 654 <para> 655 The second bug is a bit more subtle, and that is perhaps why this is 656 such a common mistake. Remember, I said the waiting loop for the read 657 handler had a bug in it. Think about what happens when we execute: 658 </para> 659 660 <programlisting> 661 while(!mouse_event) 662 { 663 </programlisting> 664 665 <para> 666 and an interrupt occurs at this point here. This causes a mouse movement 667 and wakes up the queue. 668 </para> 669 670 <programlisting> 671 interruptible_sleep_on(&mouse_wait); 672 </programlisting> 673 674 <para> 675 Now we sleep on the queue. We missed the wake up and the application 676 will not see an event until the next mouse event occurs. This will 677 lead to just the odd instance when a mouse button gets delayed. The 678 consequences to the user will probably be almost undetectable with a 679 mouse driver. With other drivers this bug could be a lot more severe. 680 </para> 681 <para> 682 There are two ways to solve this. The first is to disable interrupts 683 during the testing and the sleep. This works because when a task sleeps 684 it ceases to disable interrupts, and when it resumes it disables them 685 again. Our code thus becomes: 686 </para> 687 688 <programlisting> 689 save_flags(flags); 690 cli(); 691 692 while(!mouse_event) 693 { 694 if(file->f_flags&O_NDELAY) 695 { 696 restore_flags(flags); 697 return -EAGAIN; 698 } 699 interruptible_sleep_on(&mouse_wait); 700 if(signal_pending(current)) 701 { 702 restore_flags(flags); 703 return -ERESTARTSYS; 704 } 705 } 706 restore_flags(flags); 707 </programlisting> 708 709 <para> 710 This is the sledgehammer approach. It works but it means we spend a 711 lot more time turning interrupts on and off. It also affects 712 interrupts globally and has bad properties on multiprocessor machines 713 where turning interrupts off globally is not a simple operation, but 714 instead involves kicking each processor, waiting for them to disable 715 interrupts and reply. 716 </para> 717 <para> 718 The real problem is the race between the event testing and the sleeping. 719 We can avoid that by using the scheduling functions more directly. 720 Indeed this is the way they generally should be used for an interrupt. 721 </para> 722 723 <programlisting> 724 struct wait_queue wait = { current, NULL }; 725 726 add_wait_queue(&mouse_wait, &wait); 727 set_current_state(TASK_INTERRUPTIBLE); 728 729 while(!mouse_event) 730 { 731 if(file->f_flags&O_NDELAY) 732 { 733 remove_wait_queue(&mouse_wait, &wait); 734 set_current_state(TASK_RUNNING); 735 return -EWOULDBLOCK; 736 } 737 if(signal_pending(current)) 738 { 739 remove_wait_queue(&mouse_wait, &wait); 740 current->state = TASK_RUNNING; 741 return -ERESTARTSYS; 742 } 743 schedule(); 744 set_current_state(TASK_INTERRUPTIBLE); 745 } 746 747 remove_wait_wait(&mouse_wait, &wait); 748 set_current_state(TASK_RUNNING); 749 </programlisting> 750 751 <para> 752 At first sight this probably looks like deep magic. To understand how 753 this works you need to understand how scheduling and events work on 754 Linux. Having a good grasp of this is one of the keys to writing clean 755 efficient device drivers. 756 </para> 757 <para> 758 <function>add_wait_queue</function> does what its name suggests. It adds 759 an entry to the <varname>mouse_wait</varname> list. The entry in this 760 case is the entry for our current process (<varname>current</varname> 761 is the current task pointer). 762 </para> 763 <para> 764 So we start by adding an entry for ourself onto the 765 <varname>mouse_wait</varname> list. This does not put us to sleep 766 however. We are merely tagged onto the list. 767 </para> 768 <para> 769 Next we set our status to <constant>TASK_INTERRUPTIBLE</constant>. Again 770 this does not mean we are now asleep. This flag says what should happen 771 next time the process sleeps. <constant>TASK_INTERRUPTIBLE</constant> says 772 that the process should not be rescheduled. It will run from now until it 773 sleeps and then will need to be woken up. 774 </para> 775 <para> 776 The <function>wakeup_interruptible</function> call in the interrupt 777 handler can now be explained in more detail. This function is also very 778 simple. It goes along the list of processes on the queue it is given and 779 any that are marked as <constant>TASK_INTERRUPTIBLE</constant> it changes 780 to <constant>TASK_RUNNING</constant> and tells the kernel that new 781 processes are runnable. 782 </para> 783 <para> 784 Behind all the wrappers in the original code what is happening is this 785 </para> 786 787 <procedure> 788 <step> 789 <para> 790 We add ourself to the mouse wait queue 791 </para> 792 </step> 793 <step> 794 <para> 795 We mark ourself as sleeping 796 </para> 797 </step> 798 <step> 799 <para> 800 We ask the kernel to schedule tasks again 801 </para> 802 </step> 803 <step> 804 <para> 805 The kernel sees we are asleep and schedules someone else. 806 </para> 807 </step> 808 <step> 809 <para> 810 The mouse interrupt sets our state to <constant>TASK_RUNNING</constant> 811 and makes a note that the kernel should reschedule tasks 812 </para> 813 </step> 814 <step> 815 <para> 816 The kernel sees we are running again and continues our execution 817 </para> 818 </step> 819 </procedure> 820 <para> 821 This is why the apparent magic works. Because we mark ourself as 822 <constant>TASK_INTERRUPTIBLE</constant> and as we add ourselves 823 to the queue before we check if there are events pending, the race 824 condition is removed. 825 </para> 826 <para> 827 Now if an interrupt occurs after we check the queue status and before 828 we call the <function>schedule</function> function in order to sleep, 829 things work out. Instead of missing an event, we are set back to 830 <constant>TASK_RUNNING</constant> by the mouse interrupt. We still call 831 <function>schedule</function> but it will continue running our task. 832 We go back around the loop and this time there may be an event. 833 </para> 834 <para> 835 There will not always be an event. Thus we set ourselves back to 836 <constant>TASK_INTERRUPTIBLE</constant> before resuming the loop. 837 Another process doing a read may already have cleared the event flag, 838 and if so we will need to go back to sleep again. Eventually we will 839 get our event and escape. 840 </para> 841 <para> 842 Finally when we exit the loop we remove ourselves from the 843 <varname>mouse_wait</varname> queue as we are no longer interested 844 in mouse events, and we set ourself back to 845 <constant>TASK_RUNNABLE</constant> as we do not wish to go to sleep 846 again just yet. 847 </para> 848 <note> 849 <title>Note</title> 850 <para> 851 This isn't an easy topic. Don't be afraid to reread the description a 852 few times and also look at other device drivers to see how it works. 853 Finally if you can't grasp it just yet, you can use the code as 854 boilerplate to write other drivers and trust me instead. 855 </para> 856 </note> 857 </chapter> 858 859 <chapter id="asyncio"> 860 <title>Asynchronous I/O</title> 861 <para> 862 This leaves the missing feature - Asynchronous I/O. Normally UNIX 863 programs use the <function>poll</function> call (or its variant form 864 <function>select</function>) to wait for an event to occur on one of 865 multiple input or output devices. This model works well for most tasks 866 but because <function>poll</function> and <function>select</function> 867 wait for an event isn't suitable for tasks that are also continually 868 doing computation work. Such programs really want the kernel to kick 869 them when something happens rather than watch for events. 870 </para> 871 <para> 872 Poll is akin to having a row of lights in front of you. You can see at a 873 glance which ones if any are lit. You cannot however get anything useful 874 done while watching them. Asynchronous I/O uses signals which work more 875 like a door bell. Instead of you watching, it tells you that something 876 is up. 877 </para> 878 <para> 879 Asynchronous I/O sends the signal SIGIO to a user process when the I/O 880 events occur. In this case that means when people move the mouse. The 881 SIGIO signal causes the user process to jump to its signal handler and 882 execute code in that handler before returning to whatever was going on 883 previously. It is the application equivalent of an interrupt handler. 884 </para> 885 <para> 886 Most of the code needed for this operation is common to all its users. 887 The kernel provides a simple set of functions for managing asynchronous 888 I/O. 889 </para> 890 <para> 891 Our first job is to allow users to set asynchronous I/O on file handles. 892 To do that we need to add a new function to the file operations table for 893 our mouse: 894 </para> 895 896 <programlisting> 897struct file_operations our_mouse_fops = { 898 owner: THIS_MODULE 899 read: read_mouse, /* You can read a mouse */ 900 write: write_mouse, /* This won't do a lot */ 901 poll: poll_mouse, /* Poll */ 902 open: open_mouse, /* Called on open */ 903 release: close_mouse, /* Called on close */ 904 fasync: fasync_mouse, /* Asynchronous I/O */ 905}; 906 </programlisting> 907 908 <para> 909 Once we have installed this entry the kernel knows we support 910 asynchronous I/O and will allow all the relevant operations on the 911 device. Whenever a user adds or removes asynchronous I/O notification 912 on a file handle it calls our <function>fasync_mouse</function> routine 913 we just added. This routine uses the helper functions to keep the queue 914 of handles up to date: 915 </para> 916 917 <programlisting> 918static struct fasync_struct *mouse_fasync = NULL; 919 920static int fasync_mouse(int fd, struct file *filp, int on) 921{ 922 int retval = fasync_helper(fd, filp, on, &mouse_fasync); 923 924 if (retval < 0) 925 return retval; 926 return 0; 927} 928 </programlisting> 929 930 <para> 931 The fasync helper adds and deletes entries by managing the supplied 932 list. We also need to remove entries from this list when the file is 933 closed. This requires we add one line to our close function: 934 </para> 935 936 <programlisting> 937static int close_mouse(struct inode *inode, struct file *file) 938{ 939 fasync_mouse(-1, file, 0) 940 if(--mouse_users) 941 return 0; 942 free_irq(OURMOUSE_IRQ, NULL); 943 MOD_DEC_USE_COUNT; 944 return 0; 945} 946 </programlisting> 947 948 <para> 949 When we close the file we now call our own fasync handler as if the 950 user had requested that this file cease to be used for asynchronous 951 I/O. This rather neatly cleans up any loose ends. We certainly don't 952 wait to deliver a signal for a file that no longer exists. 953 </para> 954 <para> 955 At this point the mouse driver supports all the asynchronous I/O 956 operations, and applications using them will not error. They won't 957 however work yet. We need to actually send the signals. Again the 958 kernel provides a function for handling this. 959 </para> 960 <para> 961 We update our interrupt handler a little: 962 </para> 963 964 <programlisting> 965static void ourmouse_interrupt(int irq, void *dev_id, struct pt_regs *regs) 966{ 967 char delta_x; 968 char delta_y; 969 unsigned char new_buttons; 970 971 delta_x = inb(OURMOUSE_BASE); 972 delta_y = inb(OURMOUSE_BASE+1); 973 new_buttons = inb(OURMOUSE_BASE+2); 974 975 if(delta_x || delta_y || new_buttons != mouse_buttons) 976 { 977 /* Something happened */ 978 979 spin_lock(&mouse_lock); 980 mouse_event = 1; 981 mouse_dx += delta_x; 982 mouse_dy += delta_y; 983 984 if(mouse_dx < -4096) 985 mouse_dx = -4096; 986 if(mouse_dx > 4096) 987 mouse_dx = 4096; 988 989 if(mouse_dy < -4096) 990 mouse_dy = -4096; 991 if(mouse_dy > 4096) 992 mouse_dy = 4096; 993 994 mouse_buttons = new_buttons; 995 spin_unlock(&mouse_lock); 996 997 /* Now we do asynchronous I/O */ 998 kill_fasync(&mouse_fasync, SIGIO); 999 1000 wake_up_interruptible(&mouse_wait); 1001 } 1002} 1003 </programlisting> 1004 1005 <para> 1006 The new code simply calls the <function>kill_fasync</function> routine 1007 provided by the kernel if the queue is non-empty. This sends the 1008 required signal (SIGIO in this case) to the process each file handle 1009 says should be informed about the exciting new mouse movement that 1010 just happened. 1011 </para> 1012 <para> 1013 With this in place and the bugs in the original version fixed, you now 1014 have a fully functional mouse driver using the bus mouse protocol. It 1015 will work with the <application>X window system</application>, will work 1016 with <application>GPM</application> and should work with every other 1017 application you need. <application>Doom</application> is of course the 1018 ideal way to test your new mouse driver is functioning properly. Be sure 1019 to test it thoroughly. 1020 </para> 1021 </chapter> 1022</book> 1023 1024