From: Peter Zijlstra <peterz@infradead.org>
To: John Ogness <john.ogness@linutronix.de>
Cc: linux-kernel@vger.kernel.org, Petr Mladek <pmladek@suse.com>,
Sergey Senozhatsky <sergey.senozhatsky.work@gmail.com>,
Steven Rostedt <rostedt@goodmis.org>,
Linus Torvalds <torvalds@linux-foundation.org>,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
Andrea Parri <andrea.parri@amarulasolutions.com>,
Thomas Gleixner <tglx@linutronix.de>,
Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
Subject: Re: [RFC PATCH v2 1/2] printk-rb: add a new printk ringbuffer implementation
Date: Wed, 19 Jun 2019 13:08:01 +0200 [thread overview]
Message-ID: <20190619110801.GS3436@hirez.programming.kicks-ass.net> (raw)
In-Reply-To: <87a7eebk71.fsf@linutronix.de>
On Wed, Jun 19, 2019 at 12:30:26AM +0200, John Ogness wrote:
> On 2019-06-18, Peter Zijlstra <peterz@infradead.org> wrote:
> >> +/**
> >> + * DOC: memory barriers
> >
> > What's up with that 'DOC' crap?
>
> The separate documentation in
> Documentation/core-api/printk-ringbuffer.rst references this so it
> automatically shows up in the kernel docs. An external reference
> requires the DOC keyword.
>
> Maybe the memory barrier descriptions do not belong in the kernel docs?
So i'm biased; I don't much care for Documentation/ -- code should be
readable and have sufficient comments; I hate rst and I think that
anything that detracts from reading code comments in an editor is pure
evil.
Personally, I've stopped using /** comments, live is better now.
YMMV
> Sorry. I really have no feel about what (or how) exactly I should
> document the memory barriers. I think the above comments make sense when
> someone understands the details of the implementation. But perhaps it
> should describe things such that someone without knowledge of the
> implementation would understand what the memory barriers are for? That
> would significantly increase the amount of text as I would have to
> basically explain the implementation.
>
> I would appreciate it if you could point out a source file that
> documents its memory barriers the way you would like to see these memory
> barriers documented.
Yeah, I was going to read the implementation and make suggestions; just
haven't gotten there yet.
next prev parent reply other threads:[~2019-06-19 11:08 UTC|newest]
Thread overview: 62+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-06-07 16:23 [RFC PATCH v2 0/2] printk: new ringbuffer implementation John Ogness
2019-06-07 16:23 ` [RFC PATCH v2 1/2] printk-rb: add a new printk " John Ogness
2019-06-18 4:51 ` Sergey Senozhatsky
2019-06-18 22:12 ` John Ogness
2019-06-25 6:45 ` Sergey Senozhatsky
2019-06-25 7:15 ` Sergey Senozhatsky
2019-06-25 8:44 ` John Ogness
2019-06-25 9:06 ` Petr Mladek
2019-06-25 10:03 ` Sergey Senozhatsky
2019-06-25 12:03 ` John Ogness
2019-06-26 2:08 ` Sergey Senozhatsky
2019-06-26 7:16 ` John Ogness
2019-06-26 7:45 ` Sergey Senozhatsky
2019-06-26 7:47 ` Petr Mladek
2019-06-26 7:59 ` Sergey Senozhatsky
2019-06-25 9:09 ` Sergey Senozhatsky
2019-06-18 11:12 ` Peter Zijlstra
2019-06-18 22:18 ` John Ogness
2019-06-18 11:22 ` Peter Zijlstra
2019-06-18 22:30 ` John Ogness
2019-06-19 10:46 ` Andrea Parri
2019-06-20 22:50 ` John Ogness
2019-06-21 12:16 ` Andrea Parri
2019-06-19 11:08 ` Peter Zijlstra [this message]
2019-06-18 11:47 ` Peter Zijlstra
2019-06-20 22:23 ` John Ogness
2019-06-26 22:40 ` Peter Zijlstra
2019-06-26 22:53 ` Peter Zijlstra
2019-06-28 9:50 ` John Ogness
2019-06-28 15:44 ` Peter Zijlstra
2019-06-28 16:07 ` Peter Zijlstra
2019-07-01 10:39 ` John Ogness
2019-07-01 14:10 ` Peter Zijlstra
2019-07-01 14:11 ` Peter Zijlstra
2019-06-29 21:05 ` Andrea Parri
2019-06-30 2:03 ` John Ogness
2019-06-30 14:08 ` Andrea Parri
2019-07-02 14:13 ` John Ogness
2019-06-26 22:47 ` Peter Zijlstra
2019-06-21 14:05 ` Petr Mladek
2019-06-24 8:33 ` John Ogness
2019-06-24 14:09 ` Petr Mladek
2019-06-25 13:29 ` John Ogness
2019-06-26 8:29 ` Petr Mladek
2019-06-26 9:09 ` John Ogness
2019-06-26 21:16 ` Peter Zijlstra
2019-06-26 21:43 ` John Ogness
2019-06-27 8:28 ` Petr Mladek
2019-07-04 10:33 ` [PATCH POC] printk_ringbuffer: Alternative implementation of lockless printk ringbuffer Petr Mladek
2019-07-04 14:59 ` John Ogness
2019-07-08 15:23 ` Petr Mladek
2019-07-09 1:34 ` John Ogness
2019-07-09 9:06 ` Petr Mladek
2019-07-09 10:21 ` John Ogness
2019-07-09 11:58 ` Petr Mladek
2019-08-14 3:46 ` John Ogness
2019-06-24 13:55 ` [RFC PATCH v2 1/2] printk-rb: add a new printk ringbuffer implementation John Ogness
2019-06-25 8:55 ` Sergey Senozhatsky
2019-06-25 9:19 ` John Ogness
2019-06-07 16:23 ` [RFC PATCH v2 2/2] printk-rb: add test module John Ogness
2019-06-17 21:09 ` [RFC PATCH v2 0/2] printk: new ringbuffer implementation Thomas Gleixner
2019-06-18 7:15 ` Petr Mladek
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=20190619110801.GS3436@hirez.programming.kicks-ass.net \
--to=peterz@infradead.org \
--cc=andrea.parri@amarulasolutions.com \
--cc=gregkh@linuxfoundation.org \
--cc=john.ogness@linutronix.de \
--cc=linux-kernel@vger.kernel.org \
--cc=pmladek@suse.com \
--cc=rostedt@goodmis.org \
--cc=sergey.senozhatsky.work@gmail.com \
--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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.