Re: comments style: Re: [RFC PATCH v4 1/9] printk-rb: add a new printk ringbuffer implementation

[Sergey Senozhatsky]

On (08/20/19 10:55), Petr Mladek wrote:
[..]
> > +	 *
> > +	 * Memory barrier involvement:
> > +	 *
> > +	 * If dB reads from gA, then dC reads from fG.
> > +	 * If dB reads from gA, then dD reads from fH.
> > +	 * If dB reads from gA, then dE reads from fE.
> > +	 *
> > +	 * Note that if dB reads from gA, then dC cannot read from fC.
> > +	 * Note that if dB reads from gA, then dD cannot read from fD.
> > +	 *
> > +	 * Relies on:
> > +	 *
> > +	 * RELEASE from fG to gA
> > +	 *    matching
> > +	 * ADDRESS DEP. from dB to dC
> > +	 *
> > +	 * RELEASE from fH to gA
> > +	 *    matching
> > +	 * ADDRESS DEP. from dB to dD
> > +	 *
> > +	 * RELEASE from fE to gA
> > +	 *    matching
> > +	 * ACQUIRE from dB to dE
> > +	 */
> 
> But I am not sure how much this is useful. It would take ages to decrypt
> all these shortcuts (signs) and translate them into something
> human readable. Also it might get outdated easily.
> 
> That said, I haven't found yet if there was a system in all
> the shortcuts. I mean if they can be descrypted easily
> out of head. Also I am not familiar with the notation
> of the dependencies.

Does not appear to be systematic to me, but maybe I'm missing something
obvious. For chains like

		jA->cD->hA to jB

I haven't found anything better than just git grep jA kernel/printk/
so far.

But once you'll grep for label cD, for instance, you'd see
that it's not defined. It's mentioned but not defined

	kernel/printk/ringbuffer.c:      * jA->cD->hA.
	kernel/printk/ringbuffer.c:      * RELEASE from jA->cD->hA to jB

I was thinking about renaming labels. E.g.

	dataring_desc_init()
	{
		/* di1 */
		WRITE_ONCE(desc->begin_lpos, 1);
		/* di2 */
		WRITE_ONCE(desc->next_lpos, 1);
	}

Where di stands for descriptor init.

	dataring_push()
	{
		/* dp1 */
		ret = get_new_lpos(dr, size, &begin_lpos, &next_lpos);
		...
		/* dp2 */
		smp_mb();
		...
	}

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.

	-ss