From: Sergey Senozhatsky <sergey.senozhatsky.work@gmail.com>
To: John Ogness <john.ogness@linutronix.de>
Cc: Sergey Senozhatsky <sergey.senozhatsky.work@gmail.com>,
Petr Mladek <pmladek@suse.com>,
linux-kernel@vger.kernel.org,
Andrea Parri <andrea.parri@amarulasolutions.com>,
Sergey Senozhatsky <sergey.senozhatsky@gmail.com>,
Steven Rostedt <rostedt@goodmis.org>,
Brendan Higgins <brendanhiggins@google.com>,
Peter Zijlstra <peterz@infradead.org>,
Thomas Gleixner <tglx@linutronix.de>,
Linus Torvalds <torvalds@linux-foundation.org>,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Subject: Re: comments style: Re: [RFC PATCH v4 1/9] printk-rb: add a new printk ringbuffer implementation
Date: Fri, 23 Aug 2019 14:54:45 +0900 [thread overview]
Message-ID: <20190823055445.GA7195@jagdpanzerIV> (raw)
In-Reply-To: <87a7c3f4uj.fsf@linutronix.de>
On (08/21/19 07:46), John Ogness wrote:
[..]
> The labels are necessary for the technical documentation of the
> barriers. And, after spending much time in this, I find them very
> useful. But I agree that there needs to be a better way to assign label
> names.
[..]
> > Where dp stands for descriptor push. For dataring we can add a 'dr'
> > prefix, to avoid confusion with desc barriers, which have 'd' prefix.
> > And so on. Dunno.
>
> Yeah, I spent a lot of time going in circles on this one.
[..]
> I hope that we can agree that the labels are important. And that a
> formal documentation of the barriers is also important. Yes, they are a
> lot of work, but I find it makes it a lot easier to go back to the code
> after I've been away for a while. Even now, as I go through your
> feedback on code that I wrote over a month ago, I find the formal
> comments critical to quickly understand _exactly_ why the memory
> barriers exist.
Yeah. I like those tagsi/labels, and appreciate your efforts.
Speaking about it in general, not necessarily related to printk patch set.
With or without labels/tags we still have to grep. But grep-ing is much
easier when we have labels/tags. Otherwise it's sometimes hard to understand
what to grep for - _acquire, _relaxed, smp barrier, write_once, or
anything else.
> Perhaps we should choose labels that are more clear, like:
>
> dataring_push:A
> dataring_push:B
>
> Then we would see comments like:
>
> Memory barrier involvement:
>
> If _dataring_pop:B reads from dataring_datablock_setid:A, then
> _dataring_pop:C reads from dataring_push:G.
[..]
> RELEASE from dataring_push:E to dataring_datablock_setid:A
> matching
> ACQUIRE from _dataring_pop:B to _dataring_pop:E
I thought about it. That's very informative, albeit pretty hard to maintain.
The same applies to drA or prA and any other context dependent prefix.
> But then how should the labels in the code look? Just the letter looks
> simple in code, but cannot be grepped.
Yes, good point.
> dataring_push()
> {
> ...
> /* E */
> ...
> }
If only there was something as cool as grep-ing, but cooler. Something
that "just sucks less". Something that even folks like myself could use.
Bare with me.
Apologies. This email is rather long; but it's pretty easy to read.
Let's see if this can fly.
So what I did.
I changed several LMM tags/labels definitions, so they have common format:
LMM_TAG(name)
I don't insist on this particular naming scheme, it can be improved.
======================================================================
diff --git a/kernel/printk/dataring.c b/kernel/printk/dataring.c
index e48069dc27bc..54eb28d47d30 100644
--- a/kernel/printk/dataring.c
+++ b/kernel/printk/dataring.c
@@ -577,11 +577,11 @@ char *dataring_push(struct dataring *dr, unsigned long size,
to_db_size(&size);
do {
- /* fA: */
+ /* LMM_TAG(fA) */
ret = get_new_lpos(dr, size, &begin_lpos, &next_lpos);
/*
- * fB:
+ * LMM_TAG(fB)
*
* The data ringbuffer tail may have been pushed (by this or
* any other task). The updated @tail_lpos must be visible to
@@ -621,7 +621,7 @@ char *dataring_push(struct dataring *dr, unsigned long size,
if (!ret) {
/*
- * fC:
+ * LMM_TAG(fC)
*
* Force @desc permanently invalid to minimize risk
* of the descriptor later unexpectedly being
@@ -631,14 +631,14 @@ char *dataring_push(struct dataring *dr, unsigned long size,
dataring_desc_init(desc);
return NULL;
}
- /* fE: */
+ /* LMM_TAG(fE) */
} while (atomic_long_cmpxchg_relaxed(&dr->head_lpos, begin_lpos,
next_lpos) != begin_lpos);
db = to_datablock(dr, begin_lpos);
/*
- * fF:
+ * LMM_TAG(fF)
*
* @db->id is a garbage value and could possibly match the @id. This
* would be a problem because the data block would be considered
@@ -648,7 +648,7 @@ char *dataring_push(struct dataring *dr, unsigned long size,
WRITE_ONCE(db->id, id - 1);
/*
- * fG:
+ * LMM_TAG(fG)
*
* Ensure that @db->id is initialized to a wrong ID value before
* setting @begin_lpos so that there is no risk of accidentally
@@ -668,7 +668,7 @@ char *dataring_push(struct dataring *dr, unsigned long size,
*/
smp_store_release(&desc->begin_lpos, begin_lpos);
- /* fH: */
+ /* LMM_TAG(fH) */
WRITE_ONCE(desc->next_lpos, next_lpos);
/* If this data block wraps, use @data from the content data block. */
diff --git a/kernel/printk/numlist.c b/kernel/printk/numlist.c
index 16c6ffa74b01..285e0431dbf8 100644
--- a/kernel/printk/numlist.c
+++ b/kernel/printk/numlist.c
@@ -338,7 +338,7 @@ struct nl_node *numlist_pop(struct numlist *nl)
tail_id = atomic_long_read(&nl->tail_id);
for (;;) {
- /* cB */
+ /* LMM_TAG(cB) */
while (!numlist_read(nl, tail_id, NULL, &next_id)) {
/*
* @tail_id is invalid. Try again with an
@@ -357,6 +357,7 @@ struct nl_node *numlist_pop(struct numlist *nl)
/*
* cC:
+ * LMM_TAG(cD)
*
* Make sure the node is not busy.
*/
@@ -368,7 +369,7 @@ struct nl_node *numlist_pop(struct numlist *nl)
if (r == tail_id)
break;
- /* cA: #3 */
+ /* LMM_TAG(cA) #3 */
tail_id = r;
}
======================================================================
Okay.
Next, I added the following simple quick-n-dirty perl script:
======================================================================
Subject: [PATCH] add LMM_TAG parser
Signed-off-by: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
---
scripts/ctags-parse-lmm.pl | 45 ++++++++++++++++++++++++++++++++++++++
1 file changed, 45 insertions(+)
create mode 100755 scripts/ctags-parse-lmm.pl
diff --git a/scripts/ctags-parse-lmm.pl b/scripts/ctags-parse-lmm.pl
new file mode 100755
index 000000000000..785f6945c936
--- /dev/null
+++ b/scripts/ctags-parse-lmm.pl
@@ -0,0 +1,45 @@
+#!/usr/bin/perl
+#
+# SPDX-License-Identifier: GPL-2.0
+#
+# Parse Linux Memory Model tags and add corresponding entries to the ctags file
+#
+# LMM Über Alles!
+
+use strict;
+
+sub parse($$)
+{
+ my ($t, $f) = @_;
+ my $ctags;
+ my $file;
+
+ if (!open($ctags, '>>', $t)) {
+ print "Could not open $t: $!\n";
+ exit 1;
+ }
+
+ if (!open($file, '<', $f)) {
+ print "Could not open $f: $1\n";
+ exit 1;
+ }
+
+ while (my $row = <$file>) {
+ chomp $row;
+
+ if ($row =~ m/LMM_TAG\((.+)\)/) {
+ # yup...
+ print $ctags "$1\t$f\t/LMM_TAG($1)/;\"\td\n";
+ }
+ }
+ close($file);
+ close($ctags);
+}
+
+if ($#ARGV != 1) {
+ print "Usage:\n\tscripts/ctags-parse-lmm.pl tags C-file-to-parse\n";
+ exit 1;
+}
+
+parse($ARGV[0], $ARGV[1]);
+exit 0;
--
2.23.0
======================================================================
The next thing I did was
./scripts/ctags-parse-lmm.pl ./tags kernel/printk/dataring.c
./scripts/ctags-parse-lmm.pl ./tags kernel/printk/numlist.c
./scripts/ctags-parse-lmm.pl ./tags kernel/printk/ringbuffer.c
These 3 commands added the following entries to the tags file
(I'm using ctags and vim)
======================================================================
$ tail tags
fA kernel/printk/dataring.c /LMM_TAG(fA)/;" d
fB kernel/printk/dataring.c /LMM_TAG(fB)/;" d
fC kernel/printk/dataring.c /LMM_TAG(fC)/;" d
fE kernel/printk/dataring.c /LMM_TAG(fE)/;" d
fF kernel/printk/dataring.c /LMM_TAG(fF)/;" d
fG kernel/printk/dataring.c /LMM_TAG(fG)/;" d
fH kernel/printk/dataring.c /LMM_TAG(fH)/;" d
cB kernel/printk/numlist.c /LMM_TAG(cB)/;" d
cD kernel/printk/numlist.c /LMM_TAG(cD)/;" d
cA kernel/printk/numlist.c /LMM_TAG(cA)/;" d
======================================================================
So now when I perform LMM tag search or jump to a tag definition, vim
goes exactly to the line where the corresponding LMM_TAG was defined.
Example:
kernel/printk/ringbuffer.c
RELEASE from jA->cD->hA to jB
^
C-] // jump to tag under cursor
vim goes to kernel/printk/numlist.c
360 * LMM_TAG(cD)
^
Exactly where cD was defined.
Welcome to the future!
> Andrea suggested that the documentation should be within the code, which
> I think is a good idea. Even if it means we have more comments than
> code.
I agree that such documentation is handy. It, probably, would be even better
if we could use some tooling to make it easier to use.
-ss
next prev parent reply other threads:[~2019-08-23 5:54 UTC|newest]
Thread overview: 131+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-08-07 22:26 [RFC PATCH v4 0/9] printk: new ringbuffer implementation John Ogness
2019-08-07 22:26 ` [RFC PATCH v4 1/9] printk-rb: add a new printk " John Ogness
2019-08-20 8:15 ` numlist_pop(): " Petr Mladek
2019-08-21 5:41 ` John Ogness
2019-09-04 12:19 ` Peter Zijlstra
2019-08-20 8:22 ` assign_desc() barriers: " Petr Mladek
2019-08-20 14:14 ` Petr Mladek
2019-08-21 5:52 ` John Ogness
2019-08-22 11:53 ` Petr Mladek
2019-08-25 2:06 ` John Ogness
2019-08-26 8:21 ` John Ogness
2019-08-20 8:55 ` comments style: " Petr Mladek
2019-08-20 9:27 ` Sergey Senozhatsky
2019-08-21 5:46 ` John Ogness
2019-08-22 13:50 ` Petr Mladek
2019-08-22 17:38 ` Andrea Parri
2019-08-23 10:47 ` Petr Mladek
2019-08-23 14:27 ` Andrea Parri
2019-08-23 9:49 ` Sergey Senozhatsky
2019-08-23 5:54 ` Sergey Senozhatsky [this message]
2019-08-23 10:29 ` Petr Mladek
2019-08-21 5:42 ` John Ogness
2019-08-22 12:44 ` Petr Mladek
2019-08-20 13:50 ` dataring_push() barriers " Petr Mladek
2019-08-25 2:42 ` John Ogness
2019-08-27 14:36 ` Petr Mladek
2019-08-28 13:43 ` John Ogness
2019-08-20 15:12 ` datablock reuse races " Petr Mladek
2019-08-23 9:21 ` numlist_push() barriers " Petr Mladek
2019-08-26 8:34 ` Andrea Parri
2019-08-26 8:43 ` Andrea Parri
2019-08-26 14:10 ` Petr Mladek
2019-08-26 16:01 ` Andrea Parri
2019-08-26 22:36 ` John Ogness
2019-08-27 7:40 ` Petr Mladek
2019-08-27 14:28 ` John Ogness
2019-08-27 15:07 ` Petr Mladek
2019-08-28 10:24 ` John Ogness
2019-08-23 17:18 ` numlist API " Petr Mladek
2019-08-26 23:57 ` John Ogness
2019-08-27 13:03 ` Petr Mladek
2019-08-28 7:13 ` John Ogness
2019-08-28 8:58 ` Petr Mladek
2019-08-28 14:03 ` John Ogness
2019-08-29 11:28 ` Petr Mladek
2019-09-03 7:58 ` Sergey Senozhatsky
2019-08-30 14:48 ` dataring " Petr Mladek
2019-08-07 22:26 ` [RFC PATCH v4 2/9] printk-rb: add test module John Ogness
2019-08-07 22:26 ` [RFC PATCH v4 3/9] printk-rb: fix missing includes/exports John Ogness
2019-08-07 22:26 ` [RFC PATCH v4 4/9] printk-rb: initialize new descriptors as invalid John Ogness
2019-08-20 9:23 ` Petr Mladek
2019-08-20 10:16 ` Sergey Senozhatsky
2019-08-21 5:56 ` John Ogness
2019-08-07 22:26 ` [RFC PATCH v4 5/9] printk-rb: remove extra data buffer size allocation John Ogness
2019-08-07 22:26 ` [RFC PATCH v4 6/9] printk-rb: adjust test module ringbuffer sizes John Ogness
2019-08-19 21:29 ` [PATCH] printk-rb: fix test module macro usage John Ogness
2019-08-07 22:26 ` [RFC PATCH v4 7/9] printk-rb: increase size of seq and size variables John Ogness
2019-08-07 22:26 ` [RFC PATCH v4 8/9] printk-rb: new functionality to support printk John Ogness
2019-08-20 9:59 ` Sergey Senozhatsky
2019-08-21 5:47 ` John Ogness
2019-08-07 22:26 ` [RFC PATCH v4 9/9] printk: use a new ringbuffer implementation John Ogness
2019-08-08 19:07 ` Linus Torvalds
2019-08-08 22:55 ` John Ogness
2019-08-08 23:33 ` Linus Torvalds
2019-08-08 23:45 ` Steven Rostedt
2019-08-09 0:21 ` Linus Torvalds
2019-08-09 0:48 ` Steven Rostedt
2019-08-09 1:15 ` Linus Torvalds
2019-08-09 11:15 ` Thomas Gleixner
2019-08-09 16:00 ` Linus Torvalds
2019-08-09 20:07 ` Thomas Gleixner
2019-08-09 20:20 ` Linus Torvalds
2019-08-09 6:14 ` Peter Zijlstra
2019-08-09 7:08 ` John Ogness
2019-08-09 15:57 ` Linus Torvalds
2019-08-10 5:53 ` Thomas Gleixner
2019-09-10 3:19 ` Sergey Senozhatsky
2019-08-12 9:54 ` Geert Uytterhoeven
2019-08-16 5:46 ` Dave Young
2019-08-16 5:54 ` Dave Young
2019-08-16 9:40 ` John Ogness
2019-09-04 12:35 ` [RFC PATCH v4 0/9] printk: " Peter Zijlstra
2019-09-05 13:05 ` Petr Mladek
2019-09-05 14:31 ` Peter Zijlstra
2019-09-05 15:38 ` Thomas Gleixner
2019-09-05 16:11 ` Steven Rostedt
2019-09-05 21:10 ` John Ogness
2019-09-06 9:39 ` Petr Mladek
2019-09-09 14:11 ` printk meeting at LPC Thomas Gleixner
2019-09-13 13:26 ` John Ogness
2019-09-13 14:48 ` Daniel Vetter
2019-09-15 13:47 ` John Ogness
2019-09-16 8:44 ` Daniel Vetter
2019-09-16 4:30 ` Tetsuo Handa
2019-09-16 10:46 ` Petr Mladek
2019-09-16 13:43 ` Steven Rostedt
2019-09-16 14:28 ` John Ogness
2019-09-17 8:11 ` Petr Mladek
2019-09-17 7:52 ` Petr Mladek
2019-09-17 13:02 ` Steven Rostedt
2019-09-17 13:12 ` Greg Kroah-Hartman
2019-09-17 13:37 ` Steven Rostedt
2019-09-17 14:08 ` Tetsuo Handa
2019-09-17 7:51 ` Sergey Senozhatsky
2019-09-18 1:25 ` Sergey Senozhatsky
2019-09-18 2:08 ` Steven Rostedt
2019-09-18 2:36 ` Sergey Senozhatsky
2019-09-18 5:19 ` Sergey Senozhatsky
2019-09-18 7:42 ` John Ogness
2019-09-18 8:10 ` Sergey Senozhatsky
2019-09-18 9:05 ` John Ogness
2019-09-18 9:11 ` Sergey Senozhatsky
2019-09-18 16:41 ` Petr Mladek
2019-09-18 16:48 ` Steven Rostedt
2019-09-24 14:24 ` Petr Mladek
2019-09-19 8:06 ` Daniel Vetter
2019-09-18 7:33 ` John Ogness
2019-09-18 8:08 ` Sergey Senozhatsky
2019-10-04 14:48 ` Tony Asleson
2019-10-07 12:01 ` Petr Mladek
2019-09-06 9:06 ` [RFC PATCH v4 0/9] printk: new ringbuffer implementation Peter Zijlstra
2019-09-06 10:09 ` Sergey Senozhatsky
2019-09-06 10:49 ` Peter Zijlstra
2019-09-06 13:44 ` Sergey Senozhatsky
2019-09-06 12:42 ` Petr Mladek
2019-09-06 14:01 ` Peter Zijlstra
2019-09-06 14:22 ` Peter Zijlstra
2019-09-06 19:53 ` Sergey Senozhatsky
2019-09-06 22:47 ` John Ogness
2019-09-08 22:18 ` Peter Zijlstra
2019-09-10 3:22 ` Sergey Senozhatsky
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190823055445.GA7195@jagdpanzerIV \
--to=sergey.senozhatsky.work@gmail.com \
--cc=andrea.parri@amarulasolutions.com \
--cc=brendanhiggins@google.com \
--cc=gregkh@linuxfoundation.org \
--cc=john.ogness@linutronix.de \
--cc=linux-kernel@vger.kernel.org \
--cc=peterz@infradead.org \
--cc=pmladek@suse.com \
--cc=rostedt@goodmis.org \
--cc=sergey.senozhatsky@gmail.com \
--cc=tglx@linutronix.de \
--cc=torvalds@linux-foundation.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).