docs: Move kref.txt to core-api/kref.rst
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
@@ -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
@@ -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
@@ -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
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
mvDocumentation/kref.txtDocumentation/core-api/kref.rst// Add 'kref' tocore-api/index.rst
make cleandocs
make htmldocs 2> post.stderr
diff pre.stderr post.stderrWhile 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
Signed-off-by Tobin C. Harding <[email protected]>---
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.rstin 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.
Quoted 19 lines · Tobin C. Harding
kref.txt is already written using correct ReStructuredText format. This
can be verified as followsmake cleandocs
make htmldocs 2> pre.stderr
mvDocumentation/kref.txtDocumentation/core-api/kref.rst// Add 'kref' tocore-api/index.rst
make cleandocs
make htmldocs 2> post.stderr
diff pre.stderr post.stderrWhile 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
Signed-off-by Tobin C. Harding <[email protected]>---
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 putkboject.rstin 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
indexee1bb8983a88..1c95f0cdd239100644Documentation/core-api/index.rst +1
-0@@ -34,6 +34,7 @@ Core utilities timekeeping boot-time-mm memory-hotplug + kref Interfaces for kernel debuggingDocumentation/core-api/kref.rst renamed from Documentation/kref.txt +0
-0@@ -230,8 +230,8 @@ of the free operations that could take a longtime 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()inDocumentation/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 thatkref_get_unless_zerois enclosed in the same criticalDocumentation/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 checkingits
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 isenclosed 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 freedmemory. Note
+that it is illegal to usekref_get_unless_zerowithout checking its
return value. If you are sure (by already having a valid pointer)
that
kref_get_unless_zero()will return true, then usekref_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 memoryfor a
-rcu grace period afterrelease_entry_rcuwas called. That can be accomplished
-by usingkfree_rcu(entry, rhead)as done above, or by callingsynchronize_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 memoryfor
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@@ -159,6 +159,10 @@ kernel at the same time, called surprisinglyenough
kobject_init_and_add()::
int kobject_init_and_add(struct kobject *kobj, structkobj_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 theDocumentation/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.
Jonathan Corbet
maintainerQuoted 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.rstin core-api/ also?Oh, I should have started on
kobject.rstbefore 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
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 followsmake cleandocs
make htmldocs 2> pre.stderr
mvDocumentation/kref.txtDocumentation/core-api/kref.rst// Add 'kref' tocore-api/index.rst
make cleandocs
make htmldocs 2> post.stderr
diff pre.stderr post.stderrWhile 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
Signed-off-by Tobin C. Harding <[email protected]>---
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.
Jonathan Corbet
maintainerQuoted 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
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.
Jonathan Corbet
maintainerQuoted 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