[lkml]   [2019]   [Jun]   [19]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
SubjectRe: [RFC PATCH v2 1/2] printk-rb: add a new printk ringbuffer 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.

IMO, you could find some inspiration by looking at the memory barriers
comments from:

kernel/futex.c [header _and inline annotations]

I'll detail a single example here, and then conclude with some general

[from kernel/sched/rt.c]

static inline void rt_set_overload(struct rq *rq)
if (!rq->online)

cpumask_set_cpu(rq->cpu, rq->rd->rto_mask);
* Make sure the mask is visible before we set
* the overload count. That is checked to determine
* if we should look at the mask. It would be a shame
* if we looked at the mask, but the mask was not
* updated yet.
* Matched by the barrier in pull_rt_task().

static void pull_rt_task(struct rq *this_rq)
int this_cpu = this_rq->cpu, cpu;
bool resched = false;
struct task_struct *p;
struct rq *src_rq;
int rt_overload_count = rt_overloaded(this_rq);

if (likely(!rt_overload_count))

* Match the barrier from rt_set_overloaded; this guarantees that if we
* see overloaded we must also see the rto_mask bit.

/* If we are the only overloaded CPU do nothing */
if (rt_overload_count == 1 &&
cpumask_test_cpu(this_rq->cpu, this_rq->rd->rto_mask))



Notice that the comments provide the following information: for _each_
memory barrier primitive,

1) the _memory accesses_ being ordered

the store to ->rto_mask and the store to ->rto_count for the smp_wmb()
the load from ->rto_count and the from ->rto_mask for the smp_rmb()

2) the _matching barrier_ (and its location)

3) an informal description of the _underlying guarantee(s)_ (c.f.,
"if we see overloaded we must also see the rto_mask bit").

One can provide this information by embedding some snippet/pseudo-code
in its comments as illustrated in the examples pointed out above.

I'd suggest to _not be stingy with memory barriers explanations: this
eases/makes it possible the review itself as well as future changes or
fixes to the implementation.

FWIW (and as anticipated time ago in a private email), when I see code
like this I tend to look elsewhere... ;-/


 \ /
  Last update: 2019-06-19 12:47    [W:0.081 / U:69.408 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site