Re: [RFC PATCH v2 1/2] printk-rb: add a new printk ringbuffer implementation

[Peter Zijlstra <peterz@infradead.org>]

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.