[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.

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">

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>

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

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",

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.