patch-2.4.11-dontuse linux/Documentation/DocBook/mousedrivers.tmpl

• Lines: 142
• Date: Sun Sep 30 12:26:05 2001
• Orig file: v2.4.10/linux/Documentation/DocBook/mousedrivers.tmpl
• Orig date: Thu Jan 4 12:50:12 2001

diff -u --recursive --new-file v2.4.10/linux/Documentation/DocBook/mousedrivers.tmpl linux/Documentation/DocBook/mousedrivers.tmpl
@@ -241,16 +241,12 @@
 
   <programlisting>
 struct file_operations our_mouse_fops = {
-        NULL,                   /* Mice don't seek */
-        read_mouse,             /* You can read a mouse */
-        write_mouse,            /* This won't do a lot */
-        NULL,                   /* No readdir - not a directory */
-        poll_mouse,             /* Poll */
-        NULL,                   /* No ioctl calls */
-        NULL,                   /* No mmap */
-        open_mouse,             /* Called on open */
-        NULL,                   /* Flush - 2.2+ only */
-        close_mouse,            /* Called on close */
+        owner: THIS_MODULE,            /* Automatic usage management */
+        read:  read_mouse,             /* You can read a mouse */
+        write: write_mouse,            /* This won't do a lot */
+        poll:  poll_mouse,             /* Poll */
+        open:  open_mouse,             /* Called on open */
+        release: close_mouse,          /* Called on close */
 };
   </programlisting>
 
@@ -262,6 +258,18 @@
     configuration interfaces via ioctl calls.
   </para>
   <para>
+    The syntax we use is not standard C as such. GCC provides the ability
+    to initialise fields by name, and this generally makes the method table
+    much easier to read than counting through NULL pointers and remembering
+    the order by hand.
+  </para>
+  <para>
+    The owner field is used to manage the locking of module load an
+    unloading. It is obviously important that a module is not unloaded while
+    in use. When your device is opened the module specified by "owner" is 
+    locked. When it is finally released the module is unlocked.
+  </para>
+  <para>
     The open and close routines need to manage enabling and disabling the 
     interrupts for the mouse as well as stopping the mouse being unloaded
     when it is no longer required. 
@@ -278,12 +286,9 @@
         if(mouse_users++)
                 return 0;
 
-	MOD_INC_USE_COUNT;
-
         if(request_irq(mouse_intr, OURMOUSE_IRQ, 0, "ourmouse", NULL))
         {
                 mouse_users--;
-	        MOD_DEC_USE_COUNT;
                 return -EBUSY;
         }
         mouse_dx = 0;
@@ -301,11 +306,6 @@
     <returnvalue>0</returnvalue> for success.
   </para>
   <para>
-    Firstly we use <function>MOD_INC_USE_COUNT</function> to ensure that 
-    while the mouse is open nobody will unload it and cause a nasty crash.
-    We must do this before we sleep - and grabbing the interrupt might sleep.
-  </para>
-  <para>
     We grab the interrupt and thus start mouse interrupts. If the interrupt 
     has been borrowed by some other driver then <function>request_irq</function>
     will fail and we will return an error. If we were capable of sharing an 
@@ -328,7 +328,6 @@
         if(--mouse_users)
                 return 0;
         free_irq(OURMOUSE_IRQ, NULL);
-        MOD_DEC_USE_COUNT;
         return 0;
 }
   </programlisting>
@@ -336,8 +335,7 @@
     We count off a user and provided that there are still other users need 
     take no further action. The last person closing the mouse causes us to 
     free up the interrupt. This stops interrupts from the mouse from using 
-    our CPU time, and lets us use <function>MOD_DEC_USE_COUNT</function> so 
-    that the mouse can now be unloaded.
+    our CPU time, and ensures that the mouse can now be unloaded.
   </para>
   <para>
     We can fill in the write handler at this point as the write function for 
@@ -718,14 +716,14 @@
         struct wait_queue wait = { current, NULL };
 
         add_wait_queue(&amp;mouse_wait, &amp;wait);
-        current-&gt;state = TASK_INTERRUPTIBLE;
+        set_current_state(TASK_INTERRUPTIBLE);
         
         while(!mouse_event)
         {
                 if(file-&gt;f_flags&amp;O_NDELAY)
                 {
                         remove_wait_queue(&amp;mouse_wait, &amp;wait);
-                        current-&gt;state = TASK_RUNNING;
+                        set_current_state(TASK_RUNNING);
                         return -EWOULDBLOCK;
                 }
                 if(signal_pending(current))
@@ -735,11 +733,11 @@
                         return -ERESTARTSYS;
                 }
                 schedule();
-                current-&gt;state = TASK_INTERRUPTIBLE;
+                set_current_state(TASK_INTERRUPTIBLE);
         }
         
         remove_wait_wait(&amp;mouse_wait, &amp;wait);
-        current-&gt;state = TASK_RUNNING;
+        set_current_state(TASK_RUNNING);
   </programlisting>
 
   <para>
@@ -889,18 +887,13 @@
 
   <programlisting>
 struct file_operations our_mouse_fops = {
-        NULL,                   /* Mice don't seek */
-        read_mouse,             /* You can read a mouse */
-        write_mouse,            /* This won't do a lot */
-        NULL,                   /* No readdir - not a directory */
-        poll_mouse,             /* Poll */
-        NULL,                   /* No ioctl calls */
-        NULL,                   /* No mmap */
-        open_mouse,             /* Called on open */
-        NULL,                   /* Flush */
-        close_mouse,            /* Called on close */
-        NULL,                   /* No fsync on a mouse */
-        fasync_mouse,           /* Asynchronous I/O */
+        owner: THIS_MODULE
+        read:  read_mouse,      /* You can read a mouse */
+        write: write_mouse,     /* This won't do a lot */
+        poll:  poll_mouse,      /* Poll */
+        open:  open_mouse,      /* Called on open */
+        release: close_mouse,   /* Called on close */
+        fasync: fasync_mouse,   /* Asynchronous I/O */
 };
   </programlisting>