From b8b7074f9ee0d7edcf40ddbc41fa85f7ca30a292 Mon Sep 17 00:00:00 2001
From: Alan Stern <stern@rowland.harvard.edu>
Date: Tue, 17 Jan 2012 11:39:00 -0500
Subject: [PATCH] --- yaml --- r: 286952 b: refs/heads/master c:
 b10d5efdf7892d18b3b7d899edce2c8d9b80aea9 h: refs/heads/master v: v3

---
 [refs]                    |  2 +-
 trunk/drivers/base/core.c | 15 +++++++++++++++
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/[refs] b/[refs]
index 4a0f7c43bae1..ddb2cda1ccb2 100644
--- a/[refs]
+++ b/[refs]
@@ -1,2 +1,2 @@
 ---
-refs/heads/master: 4f4ffe52e1e5ddb9708fe075aaef4424f1fb744a
+refs/heads/master: b10d5efdf7892d18b3b7d899edce2c8d9b80aea9
diff --git a/trunk/drivers/base/core.c b/trunk/drivers/base/core.c
index 4a67cc0c8b37..ad29e928baaa 100644
--- a/trunk/drivers/base/core.c
+++ b/trunk/drivers/base/core.c
@@ -632,6 +632,11 @@ static void klist_children_put(struct klist_node *n)
  * may be used for reference counting of @dev after calling this
  * function.
  *
+ * All fields in @dev must be initialized by the caller to 0, except
+ * for those explicitly set to some other value.  The simplest
+ * approach is to use kzalloc() to allocate the structure containing
+ * @dev.
+ *
  * NOTE: Use put_device() to give up your reference instead of freeing
  * @dev directly once you have called this function.
  */
@@ -930,6 +935,13 @@ int device_private_init(struct device *dev)
  * to the global and sibling lists for the device, then
  * adds it to the other relevant subsystems of the driver model.
  *
+ * Do not call this routine or device_register() more than once for
+ * any device structure.  The driver model core is not designed to work
+ * with devices that get unregistered and then spring back to life.
+ * (Among other things, it's very hard to guarantee that all references
+ * to the previous incarnation of @dev have been dropped.)  Allocate
+ * and register a fresh new struct device instead.
+ *
  * NOTE: _Never_ directly free @dev after calling this function, even
  * if it returned an error! Always use put_device() to give up your
  * reference instead.
@@ -1090,6 +1102,9 @@ int device_add(struct device *dev)
  * have a clearly defined need to use and refcount the device
  * before it is added to the hierarchy.
  *
+ * For more information, see the kerneldoc for device_initialize()
+ * and device_add().
+ *
  * NOTE: _Never_ directly free @dev after calling this function, even
  * if it returned an error! Always use put_device() to give up the
  * reference initialized in this function instead.