Skip to contentSkip to conversation

docs: Move kref.txt to core-api/kref.rst

PATCH In review Tobin C. Harding 4 participants 8 messages May 10, 2019 – May 20, 2019 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: Move kref.txt to core-api/kref.rst

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.

---

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%)
Documentation/core-api/index.rst +1 -0
index ee1bb8983a88..1c95f0cdd239 100644
@@ -34,6 +34,7 @@ Core utilities
    timekeeping
    boot-time-mm
    memory-hotplug
+   kref
 
 
 Interfaces for kernel debugging
Documentation/core-api/kref.rst renamed from Documentation/kref.txt +12 -12
similarity index 93%
rename from Documentation/kref.txt
rename to Documentation/core-api/kref.rst
index 3af384156d7e..a2174dd09eb2 100644
@@ -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.
Documentation/kobject.txt +4 -0
index ff4c25098119..140030b4603b 100644
@@ -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.
 
Signature · 1 line
2.21.0
#1 lore raw
Quoted 15 lines · Tobin C. Harding

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.

Quoted 8 lines

---

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?

Oh, I should have started on kobject.rst before sending this. It builds without errors also. The 'conversion' is no more than renaming the file.

If this patch is acceptable I can re-spin it as part of a series that does kobject as well so you don't get merge conflicts in core-api/index

thanks,
Tobin.

maintainer
#2 lore raw
Quoted 2 lines · On Fri, 10 May 2019 10:41:04 +1000 "Tobin C. Harding" <[email protected]> wrote:
Quoted 2 lines

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

Let's just say there's a lot of obvious stuff to do in Documentation/ that nobody has gotten around to doing yet...

Quoted 9 lines
Quoted 2 lines

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

Oh, I should have started on kobject.rst before sending this. It builds without errors also. The 'conversion' is no more than renaming the file.

If this patch is acceptable I can re-spin it as part of a series that does kobject as well so you don't get merge conflicts in core-api/index

That sounds like a fine idea to me.

Thanks,

jon

Reviewed-by on v1 1/1
#3 lore raw
In reply to Tobin C. Harding
Quoted 19 lines · Tobin C. Harding

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.

Quoted 5 lines

---

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

Speaking for the two kref.txt paragraphs, the width being too large is simply an oversight from my side. I wasn't aware of the restriction.

Quoted 115 lines

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%)
Documentation/core- renamed from Documentation/core-api/index.rst +0 -0

api/index.rst
index ee1bb8983a88..1c95f0cdd239 100644

Documentation/core-api/index.rst +1 -0
@@ -34,6 +34,7 @@ Core utilities
    timekeeping
    boot-time-mm
    memory-hotplug
+   kref
 
 
 Interfaces for kernel debugging
Documentation/core-api/kref.rst renamed from Documentation/kref.txt +0 -0
similarity index 93%
rename from Documentation/kref.txt
rename to Documentation/core-api/kref.rst
index 3af384156d7e..a2174dd09eb2 100644
@@ -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

Documentation/core-api/kref.rst renamed from Documentation/kref.txt +1 -1
-the following way::
+The above example could also be optimized using

kref_get_unless_zero()

Documentation/core-api/kref.rst renamed from Documentation/kref.txt +1 -1
+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

Documentation/core-api/kref.rst renamed from Documentation/kref.txt +0 -3
-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

Documentation/core-api/kref.rst renamed from Documentation/kref.txt +2 -0
+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

Documentation/core-api/kref.rst renamed from Documentation/kref.txt +2 -0
+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.

Documentation/core-api/kref.rst renamed from Documentation/kref.txt +0 -1
@@ -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()

Documentation/core-api/kref.rst renamed from Documentation/kref.txt +1 -2
-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

Documentation/core-api/kref.rst renamed from Documentation/kref.txt +4 -0
+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.
Documentation/kobject.txt +0 -0
index ff4c25098119..140030b4603b 100644
@@ -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

Documentation/kobject.txt +2 -0
+error return is due to the 'add' part.
+
 The arguments are the same as the individual kobject_init() and
 kobject_add() functions described above.
#4 lore raw
Quoted 20 lines · Thomas Hellstrom
Quoted 19 lines · Tobin C. Harding

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.

Quoted 8 lines
Quoted 5 lines

---

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

Speaking for the two kref.txt paragraphs, the width being too large is simply an oversight from my side. I wasn't aware of the restriction.

I'm a stickler for the rules, often to peoples dismay :) AFAIK they say 80 characters for code and 72 for documentation is optimal. I'm yet to understand why 72 was chosen. Maybe because its the same length as the git commit long message but that doesn't explain where _that_ came from. I read once that they used 72 characters on punch cards at times because the other 8 characters got mangled for some reason. Anyways, its kinda anal and I only change it if it looks like doing so is not going to annoy people _too_ much or, like in this instance, if the file is super clean except for a small portion. The rest of this file seems to use 72 so I thought it was worth the change.

I'm open to being told otherwise.

Hope this is interesting for you,
Tobin.

maintainer
#5 lore raw
Quoted 2 lines · On Fri, 10 May 2019 16:45:45 -0400 "Tobin C. Harding" <[email protected]> wrote:

I read once that they used 72 characters on punch cards at times because the other 8 characters got mangled for some reason.

Those of use who worked in Fortran understand these things... columns 73-80 were ignored by the compiler. The normal use was to put line numbers in there to help recovery when you dropped your card deck on the floor and had to unshuffle things. A diagonal line drawn across the top of deck helped a lot, but it was good to have verification for the marginal cases.

Kids today just don't have any culture at all...:)

jon

#6 lore raw
Quoted 6 lines · Jonathan Corbet
Quoted 2 lines · On Fri, 10 May 2019 16:45:45 -0400 "Tobin C. Harding" <[email protected]> wrote:

I read once that they used 72 characters on punch cards at times because the other 8 characters got mangled for some reason.

Quoted 8 lines

Those of use who worked in Fortran understand these things... columns 73-80 were ignored by the compiler. The normal use was to put line numbers in there to help recovery when you dropped your card deck on the floor and had to unshuffle things. A diagonal line drawn across the top of deck helped a lot, but it was good to have verification for the marginal cases.

Kids today just don't have any culture at all...:)

I was just going through my editors init file and I see I have default column width for kernel RST files set to 75. Did you tell me that some time Jon, I vaguely remember?

+1 for the trivia

Cheers,
Tobin.

maintainer
#7 lore raw
Quoted 3 lines · On Fri, 17 May 2019 09:19:49 +1000 "Tobin C. Harding" <[email protected]> wrote:

I was just going through my editors init file and I see I have default column width for kernel RST files set to 75. Did you tell me that some time Jon, I vaguely remember?

Don't think it was me, but who knows what I might have said way back when... 75 doesn't seem outlandish, anyway.

jon