From 83b93201b84ace0f1066c3c896064efe1637fa86 Mon Sep 17 00:00:00 2001
From: Cornelia Huck <cornelia.huck@de.ibm.com>
Date: Wed, 3 Sep 2008 18:26:40 +0200
Subject: [PATCH] --- yaml --- r: 115135 b: refs/heads/master c:
 5739411acbaa63a6c22c91e340fdcdbcc7d82a51 h: refs/heads/master i:   115133:
 3ad7a45b7165a9328296ebfc5e2d6d9ce5923c13   115131:
 6fae614d3fcbf5b44f0baaa2af1168637800b517   115127:
 9a7e298a65d2ed43fa7a36c9bb546e725ff35d2e   115119:
 ebac3ce34dc57d46538e0841df18d701c87ce1d5   115103:
 3c760f2a73a92283aba68327043181d40327486d   115071:
 ba9c770cec0c1f1a1bae619b14aac64cdded498a v: v3

---
 [refs]                    |  2 +-
 trunk/drivers/base/core.c | 23 ++++++++++++++++++-----
 2 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/[refs] b/[refs]
index 31d8badd5b42..cd9671c98a0d 100644
--- a/[refs]
+++ b/[refs]
@@ -1,2 +1,2 @@
 ---
-refs/heads/master: 9cf899d12583082c77a0fcc758f3179b440518ee
+refs/heads/master: 5739411acbaa63a6c22c91e340fdcdbcc7d82a51
diff --git a/trunk/drivers/base/core.c b/trunk/drivers/base/core.c
index b98cb1416a2d..aac91e89d6af 100644
--- a/trunk/drivers/base/core.c
+++ b/trunk/drivers/base/core.c
@@ -523,11 +523,16 @@ static void klist_children_put(struct klist_node *n)
  * device_initialize - init device structure.
  * @dev: device.
  *
- * This prepares the device for use by other layers,
- * including adding it to the device hierarchy.
+ * This prepares the device for use by other layers by initializing
+ * its fields.
  * It is the first half of device_register(), if called by
- * that, though it can also be called separately, so one
- * may use @dev's fields (e.g. the refcount).
+ * that function, though it can also be called separately, so one
+ * may use @dev's fields. In particular, get_device()/put_device()
+ * may be used for reference counting of @dev after calling this
+ * function.
+ *
+ * NOTE: Use put_device() to give up your reference instead of freeing
+ * @dev directly once you have called this function.
  */
 void device_initialize(struct device *dev)
 {
@@ -835,9 +840,13 @@ static void device_remove_sys_dev_entry(struct device *dev)
  * This is part 2 of device_register(), though may be called
  * separately _iff_ device_initialize() has been called separately.
  *
- * This adds it to the kobject hierarchy via kobject_add(), adds it
+ * This adds @dev to the kobject hierarchy via kobject_add(), adds it
  * to the global and sibling lists for the device, then
  * adds it to the other relevant subsystems of the driver model.
+ *
+ * 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.
  */
 int device_add(struct device *dev)
 {
@@ -965,6 +974,10 @@ int device_add(struct device *dev)
  * I.e. you should only call the two helpers separately if
  * have a clearly defined need to use and refcount the device
  * before it is added to the hierarchy.
+ *
+ * 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.
  */
 int device_register(struct device *dev)
 {