From: Greg KH <greg@kroah.com>
To: Marcelo Tosatti <marcelo@conectiva.com.br>
Cc: linux-usb-devel@lists.sourceforge.net
Subject: [PATCH 4 of 6] USB skeleton driver documentation update

Hi,

Here's a patch against 2.4.18-pre2 that updates the USB documentation
about the usb-skeleton locking logic.  The patch was done by Chris
Rankin.

thanks,

greg k-h

diff -Nru a/drivers/usb/usb-skeleton.c b/drivers/usb/usb-skeleton.c
--- a/drivers/usb/usb-skeleton.c	Tue Jan  8 09:48:29 2002
+++ b/drivers/usb/usb-skeleton.c	Tue Jan  8 09:48:29 2002
@@ -138,9 +138,37 @@
 /* lock to protect the minor_table structure */
 static DECLARE_MUTEX (minor_table_mutex);
 
-/* file operations needed when we register this driver */
+/*
+ * File operations needed when we register this driver.
+ * This assumes that this driver NEEDS file operations,
+ * of course, which means that the driver is expected
+ * to have a node in the /dev directory. If the USB
+ * device were for a network interface then the driver
+ * would use "struct net_driver" instead, and a serial
+ * device would use "struct tty_driver". 
+ */
 static struct file_operations skel_fops = {
+	/*
+	 * The owner field is part of the module-locking
+	 * mechanism. The idea is that the kernel knows
+	 * which module to increment the use-counter of
+	 * BEFORE it calls the device's open() function.
+	 * This also means that the kernel can decrement
+	 * the use-counter again before calling release()
+	 * or should the open() function fail.
+	 *
+	 * Not all device structures have an "owner" field
+	 * yet. "struct file_operations" and "struct net_device"
+	 * do, while "struct tty_driver" does not. If the struct
+	 * has an "owner" field, then initialize it to the value
+	 * THIS_MODULE and the kernel will handle all module
+	 * locking for you automatically. Otherwise, you must
+	 * increment the use-counter in the open() function
+	 * and decrement it again in the release() function
+	 * yourself.
+	 */
 	owner:		THIS_MODULE,
+
 	read:		skel_read,
 	write:		skel_write,
 	ioctl:		skel_ioctl,
@@ -215,7 +243,11 @@
 		return -ENODEV;
 	}
 
-	/* increment our usage count for the module */
+	/* Increment our usage count for the module.
+	 * This is redundant here, because "struct file_operations"
+	 * has an "owner" field. This line is included here soley as
+	 * a reference for drivers using lesser structures... ;-)
+	 */
 	MOD_INC_USE_COUNT;
 
 	/* lock our minor table and get our local data for this minor */
@@ -278,8 +310,8 @@
 		/* the device was unplugged before the file was released */
 		up (&dev->sem);
 		skel_delete (dev);
-		MOD_DEC_USE_COUNT;
 		up (&minor_table_mutex);
+		MOD_DEC_USE_COUNT;
 		return 0;
 	}