[PATCH] don't mention MOD_INC_USE_COUNT/MOD_DEC_USE_COUNT in docs

From: Christoph Hellwig <hch@lst.de>

If we want new drivers to not use obsolete interfaces we're better off not
mentioning it in the documentation.

diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl
index 9cf7cd0cdb57e62ea93af11df60fc931dedecd6f..0424c92f5db184e697ecfd8f943a2e3c2068f189 100644 (file)
--- a/Documentation/DocBook/kernel-hacking.tmpl
+++ b/Documentation/DocBook/kernel-hacking.tmpl
@@ -779,62 +779,7 @@ printk(KERN_INFO "my ip: %d.%d.%d.%d\n", NIPQUAD(ipaddress));
    </para>
   </sect1>
 
-  <sect1 id="routines-module-use-counters">
-   <title> <function>MOD_INC_USE_COUNT</function>/<function>MOD_DEC_USE_COUNT</function>
-    <filename class="headerfile">include/linux/module.h</filename></title>
-
-   <para>
-    These manipulate the module usage count, to protect against
-    removal (a module also can't be removed if another module uses
-    one of its exported symbols: see below).  Every reference to
-    the module from user context should be reflected by this
-    counter (e.g. for every data structure or socket) before the
-    function sleeps.  To quote Tim Waugh:
-   </para>
-
-   <programlisting>
-/* THIS IS BAD */
-foo_open (...)
-{
-        stuff..
-        if (fail)
-                return -EBUSY;
-        sleep.. (might get unloaded here)
-        stuff..
-        MOD_INC_USE_COUNT;
-        return 0;
-}
-
-/* THIS IS GOOD /
-foo_open (...)
-{
-        MOD_INC_USE_COUNT;
-        stuff..
-        if (fail) {
-                MOD_DEC_USE_COUNT;
-                return -EBUSY;
-        }
-        sleep.. (safe now)
-        stuff..
-        return 0;
-}
-   </programlisting>
-
-   <para>
-   You can often avoid having to deal with these problems by using the 
-   <structfield>owner</structfield> field of the 
-   <structname>file_operations</structname> structure. Set this field
-   as the macro <symbol>THIS_MODULE</symbol>.
-   </para>
-
-   <para>
-   For more complicated module unload locking requirements, you can set the
-   <structfield>can_unload</structfield> function pointer to your own routine,
-   which should return <returnvalue>0</returnvalue> if the module is
-   unloadable, or <returnvalue>-EBUSY</returnvalue> otherwise.
-   </para> 
-  
-  </sect1>
+ <!-- add info on new-style module refcounting here -->
  </chapter>
 
  <chapter id="queues">

diff --git a/Documentation/DocBook/videobook.tmpl b/Documentation/DocBook/videobook.tmpl
index b942a25a47536a38ad01fc1b92da619427db606f..45243eeb23610ca5ce7421d1ae64f54faef97d38 100644 (file)
--- a/Documentation/DocBook/videobook.tmpl
+++ b/Documentation/DocBook/videobook.tmpl
@@ -232,7 +232,6 @@ static int radio_open(stuct video_device *dev, int flags)
         if(users)
                 return -EBUSY;
         users++;
-        MOD_INC_USE_COUNT;
         return 0;
 }
 
@@ -248,7 +247,6 @@ static int radio_open(stuct video_device *dev, int flags)
 static int radio_close(struct video_device *dev)
 {
         users--;
-        MOD_DEC_USE_COUNT;
 }
 
   </programlisting>
@@ -954,7 +952,6 @@ static int camera_open(stuct video_device *dev, int flags)
         if(request_irq(irq, camera_irq, 0, "camera", dev)&lt;0)
                 return -EBUSY;
         users++;
-        MOD_INC_USE_COUNT;
         return 0;
 }
 
@@ -963,7 +960,6 @@ static int camera_close(struct video_device *dev)
 {
         users--;
         free_irq(irq, dev);
-        MOD_DEC_USE_COUNT;
 }
   </programlisting>
   <para>

diff --git a/Documentation/cdrom/cdrom-standard.tex b/Documentation/cdrom/cdrom-standard.tex
index af1c93a32780bfe221d50514b4b5914821ded060..0a51967fe49e0f392422e3138111f29a73e316c8 100644 (file)
--- a/Documentation/cdrom/cdrom-standard.tex
+++ b/Documentation/cdrom/cdrom-standard.tex
@@ -352,11 +352,6 @@ user commands {\tt {dd}} or {\tt {cat}}.
 \item[1] Open for $ioctl$ commands, as done by audio-CD playing
 programs.
 \end{itemize}
-In case the driver supports modules, the call $MOD_INC_USE_COUNT$
-should be performed exactly once, if the $open()$ was successful. The
-return value is negative on error, and zero on success. The
-open-for-ioctl call can only fail if there is no hardware.
-
 Notice that any strategic code (closing tray upon $open()$, etc.)\ is
 done by the calling routine in \cdromc, so the low-level routine
 should only be concerned with proper initialization, such as spinning

diff --git a/Documentation/i2c/i2c-old-porting b/Documentation/i2c/i2c-old-porting
index 0bb04120c3ec6a39bc54dea43445e13fdcaf848e..158dfe550a3f77744e655d9f5aaa83523b23f2ee 100644 (file)
--- a/Documentation/i2c/i2c-old-porting
+++ b/Documentation/i2c/i2c-old-porting
@@ -386,7 +386,6 @@ based on the above guide (for clarity).
 +      if(client == NULL) 
                return -ENOMEM;
 -
--      MOD_INC_USE_COUNT;
 +      client_template.adapter = adap;
 +      client_template.addr = addr;
 +      memcpy(client, &client_template, sizeof(*client));
@@ -432,7 +431,6 @@ based on the above guide (for clarity).
  
 +      init_MUTEX(&decoder->lock);
 +      i2c_attach_client(client);
-+      MOD_INC_USE_COUNT;
        /* setup and implicit mode 0 select has been performed */
        return 0;
  }
@@ -463,7 +461,6 @@ based on the above guide (for clarity).
 +      kfree(decoder);
 +      kfree(client);
  
-       MOD_DEC_USE_COUNT;
        return 0;
  }
  
@@ -593,12 +590,15 @@ based on the above guide (for clarity).
 -      I2C_SAA7110, I2C_SAA7110+1,     /* Addr range */
 -
 -      saa7110_attach,
-+      IF_NAME,                        /* name */
-+      I2C_DRIVERID_SAA7110,   /* in i2c.h */
-+      I2C_DF_NOTIFY,  /* Addr range */
-+      saa7110_probe,
-       saa7110_detach,
-       saa7110_command
+-      saa7110_detach,
+-      saa7110_command
++      .owner          = THIS_MODULE,
++      .name           = IF_NAME,
++      .id             = I2C_DRIVERID_SAA7110,
++      .flags          = I2C_DF_NOTIFY,
++      .attach_adapter = saa7110_probe,
++      .detach_adapter = saa7110_detach,
++      .command        = saa7110_command,
  };
 +static struct i2c_client client_template = {
 +      "saa7110_client",

diff --git a/Documentation/isdn/INTERFACE b/Documentation/isdn/INTERFACE
index 3b56e226f4e93e27f6c1c1725f75a6def109b7d0..5df17e5b25c85f5fd9b808558a2f177be2aac4fa 100644 (file)
--- a/Documentation/isdn/INTERFACE
+++ b/Documentation/isdn/INTERFACE
@@ -412,30 +412,6 @@ Description of the Interface between Linklevel and Hardwarelevel
     Returnvalue:
       current protocol-Id (one of the constants ISDN_L3_PROTO)
 
-  ISDN_CMD_LOCK:
-
-    With this command the HL-driver is told, that it will be used by the
-    LL and therefore may not be unloaded. The HL-driver should use
-    MOD_INC_USE_COUNT to tell that to the kernel.
-
-    Parameter:
-      driver      = driver-Id.
-      command     = ISDN_CMD_LOCK
-      arg         = unused.
-      parm        = unused.
-
-  ISDN_CMD_UNLOCK:
-
-    With this command the HL-driver is told, that it is no more used by the
-    LL and therefore may be unloaded. The HL-driver should use
-    DEC_INC_USE_COUNT to tell that to the kernel.
-
-    Parameter:
-      driver      = driver-Id.
-      command     = ISDN_CMD_UNLOCK
-      arg         = unused.
-      parm        = unused.
-
   ISDN_CMD_PROCEED: 
 
     With this command, the HL-driver is told to proceed with a incoming call.