Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
From:   "Tobin C. Harding" <tobin@kernel.org>
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     "Tobin C. Harding" <tobin@kernel.org>,
        Corey Minyard <minyard@acm.org>,
        Thomas Hellstrom <thellstrom@vmware.com>,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: [PATCH] docs: Move kref.txt to core-api/kref.rst
Date:   Fri, 10 May 2019 10:17:47 +1000
Message-Id: <20190510001747.8767-1-tobin@kernel.org>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

kref.txt is already written using correct ReStructuredText format.  This
can be verified as follows

	make cleandocs
	make htmldocs 2> pre.stderr
	mv Documentation/kref.txt Documentation/core-api/kref.rst
	// Add 'kref' to core-api/index.rst
	make cleandocs
	make htmldocs 2> post.stderr
	diff pre.stderr post.stderr

While doing the file move, fix the column width to be 72 characters wide
as it is throughout the document.  This is whitespace only.  kref.txt is
so cleanly written its a shame to have these few extra wide paragraphs.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---

I'm always hesitant to do docs patches that seem obvious - is there
some reason that this was not done previously?

I did this one in preparation for converting kobject.txt, my intent is
to put kboject.rst in core-api/ also?

I can split the whitespace change and the file rename into separate
patches if you'd prefer.

thanks,
Tobin.

 Documentation/core-api/index.rst              |  1 +
 Documentation/{kref.txt => core-api/kref.rst} | 24 +++++++++----------
 Documentation/kobject.txt                     |  4 ++++
 3 files changed, 17 insertions(+), 12 deletions(-)
 rename Documentation/{kref.txt => core-api/kref.rst} (93%)

diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index ee1bb8983a88..1c95f0cdd239 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -34,6 +34,7 @@ Core utilities
    timekeeping
    boot-time-mm
    memory-hotplug
+   kref
 
 
 Interfaces for kernel debugging
diff --git a/Documentation/kref.txt b/Documentation/core-api/kref.rst
similarity index 93%
rename from Documentation/kref.txt
rename to Documentation/core-api/kref.rst
index 3af384156d7e..a2174dd09eb2 100644
--- a/Documentation/kref.txt
+++ b/Documentation/core-api/kref.rst
@@ -230,8 +230,8 @@ of the free operations that could take a long time or might claim the
 same lock.  Note that doing everything in the release routine is still
 preferred as it is a little neater.
 
-The above example could also be optimized using kref_get_unless_zero() in
-the following way::
+The above example could also be optimized using kref_get_unless_zero()
+in the following way::
 
 	static struct my_data *get_entry()
 	{
@@ -261,11 +261,11 @@ the following way::
 		kref_put(&entry->refcount, release_entry);
 	}
 
-Which is useful to remove the mutex lock around kref_put() in put_entry(), but
-it's important that kref_get_unless_zero is enclosed in the same critical
-section that finds the entry in the lookup table,
-otherwise kref_get_unless_zero may reference already freed memory.
-Note that it is illegal to use kref_get_unless_zero without checking its
+Which is useful to remove the mutex lock around kref_put() in
+put_entry(), but it's important that kref_get_unless_zero is enclosed in
+the same critical section that finds the entry in the lookup table,
+otherwise kref_get_unless_zero may reference already freed memory.  Note
+that it is illegal to use kref_get_unless_zero without checking its
 return value. If you are sure (by already having a valid pointer) that
 kref_get_unless_zero() will return true, then use kref_get() instead.
 
@@ -312,8 +312,8 @@ locking for lookups in the above example::
 		kref_put(&entry->refcount, release_entry_rcu);
 	}
 
-But note that the struct kref member needs to remain in valid memory for a
-rcu grace period after release_entry_rcu was called. That can be accomplished
-by using kfree_rcu(entry, rhead) as done above, or by calling synchronize_rcu()
-before using kfree, but note that synchronize_rcu() may sleep for a
-substantial amount of time.
+But note that the struct kref member needs to remain in valid memory for
+a rcu grace period after release_entry_rcu was called. That can be
+accomplished by using kfree_rcu(entry, rhead) as done above, or by
+calling synchronize_rcu() before using kfree, but note that
+synchronize_rcu() may sleep for a substantial amount of time.
diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt
index ff4c25098119..140030b4603b 100644
--- a/Documentation/kobject.txt
+++ b/Documentation/kobject.txt
@@ -159,6 +159,10 @@ kernel at the same time, called surprisingly enough kobject_init_and_add()::
     int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
                              struct kobject *parent, const char *fmt, ...);
 
+An error return from kobject_init_and_add() must be followed by a call to
+kobject_put() since the 'init' part of this function is always called and the
+error return is due to the 'add' part.
+
 The arguments are the same as the individual kobject_init() and
 kobject_add() functions described above.
 
-- 
2.21.0