Re: [PATCH 2/2] docs/misra: add Rule 5.1

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Thu, 26 May 2022, Jan Beulich wrote:
> On 26.05.2022 03:18, Stefano Stabellini wrote:
> > On Wed, 25 May 2022, Jan Beulich wrote:
> >> On 25.05.2022 02:35, Stefano Stabellini wrote:
> >>> From: Stefano Stabellini <stefano.stabellini@xxxxxxxxxx>
> >>>
> >>> Add Rule 5.1, with the additional note that the character limit for Xen
> >>> is 63 characters.
> >>>
> >>> The max length identifiers found by ECLAIR are:
> >>>
> >>> __mitigate_spectre_bhb_clear_insn_start
> >>> domain_pause_by_systemcontroller_nosync
> >>>
> >>> Both of them are 40 characters long. A limit of 63 characters work for
> >>> the existing code.
> >>
> >> I have to admit that it hasn't become clear to me why we want to
> >> permit (if not to say encourage) the use of such long identifiers.
> >> If 40 is the longest we've got, why not limit it to 40 for now
> >> with a goal of further reducing? A 40-char symbol plus some
> >> indentation will already pose problems with 80-char line length.
> >  
> > We can go lower than 63 if we want to. I chose the closest power-of-two
> > length -1 for the NUL terminator. But it doesn't have to be a
> > power-of-two. So we could go with "41" if we want to.
> > 
> > Anyone in favor of that? I am happy with any number between 41 and 63.
> 
> Why 41, not 40? 41 seems yet more arbitrary to me than e.g. 40.

I was adding +1 to account for the NUL terminator, but actually I
already added it before (__mitigate_spectre_bhb_clear_insn_start and
domain_pause_by_systemcontroller_nosync are 39 characters).

So yes we can go with 40.


> >> Otoh, as said on the call, I think the public headers want
> >> mentioning explicitly here in some way. Part of them (most or all
> >> of what's under io/) aren't used when building Xen, so won't be
> >> seen by Eclair (aiui). Yet they are a formal part of the code
> >> base, and e.g. ring.h has some pretty long names (albeit still
> >> below 40 chars as it looks). So once we're able to go down to e.g.
> >> 32 for the bulk of the code base, public headers should imo still
> >> be explicitly allowed to use longer identifiers.
> > 
> > Actually I thought about writing something for the public header but I
> > wasn't sure what to write. What about:
> > 
> > - Note: the Xen characters limit for identifiers is 41. Public headers
> >   (xen/include/public/) are allowed to retain longer identifiers for
> >   backward compatibility.
> 
> Fine with me, except I wonder in how far going forward we actually
> need to play by that limit there. Proper name-spacing is particularly
> important in the public headers, so may warrant a higher limit for
> certain (unusual?) circumstances.

Keep in mind that the rules are general guidelines and good defaults.
There can be always special cases, and that is especially true for
"unusual circumstances".