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;
Date:   Tue, 18 Jun 2019 13:22:37 +0200
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
Message-ID: <20190618112237.GP3436@hirez.programming.kicks-ass.net>
References: <20190607162349.18199-1-john.ogness@linutronix.de>
 <20190607162349.18199-2-john.ogness@linutronix.de>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20190607162349.18199-2-john.ogness@linutronix.de>
User-Agent: Mutt/1.10.1 (2018-07-13)
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Fri, Jun 07, 2019 at 06:29:48PM +0206, John Ogness wrote:
> +/**
> + * DOC: memory barriers

What's up with that 'DOC' crap?

> + *
> + * Writers
> + * -------
> + * The main issue with writers is expiring/invalidating old data blocks in
> + * order to create new data blocks. This is performed in 6 steps that must
> + * be observed in order by all writers to allow cooperation. Here is a list
> + * of the 6 steps and the named acquire/release memory barrier pairs that
> + * are used to synchronized them:
> + *
> + * * old data invalidation (MB1): Pushing rb.data_list.oldest forward.
> + *   Necessary for identifying if data has been expired.
> + *
> + * * new data reservation (MB2): Pushing rb.data_list.newest forward.
> + *   Necessary for validating data.
> + *
> + * * assign the data block to a descriptor (MB3): Setting data block id to
> + *   descriptor id. Necessary for finding the descriptor associated with th
> + *   data block.
> + *
> + * * commit data (MB4): Setting data block data_next. (Now data block is
> + *   valid). Necessary for validating data.
> + *
> + * * make descriptor newest (MB5): Setting rb.descr_list.newest to descriptor.
> + *   (Now following new descriptors will be linked to this one.) Necessary for
> + *   ensuring the descriptor's next is set to EOL before adding to the list.
> + *
> + * * link descriprtor to previous newest (MB6): Setting the next of the
> + *   previous descriptor to this one. Necessary for correctly identifying if
> + *   a descriptor is the only descriptor on the list.
> + *
> + * Readers
> + * -------
> + * Readers only make of smb_rmb() to ensure that certain critical load
> + * operations are performed in an order that allows readers to evaluate if
> + * the data they read is really valid.
> + */

This isn't really helping much I feel. It doesn't begin to describe the
ordering. But maybe the code makes more sense.