linux-kernel - Re: [PATCH] docs: use flexible array members, not zero-length

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20190928105557.221fb119@heffalump.sk2.org>
Date:   Sat, 28 Sep 2019 10:55:57 +0200
From:   Stephen Kitt <steve@....org>
To:     Jonathan Corbet <corbet@....net>
Cc:     linux-doc@...r.kernel.org, bpf@...r.kernel.org,
        linux-kernel@...r.kernel.org, linux-remoteproc@...r.kernel.org,
        linux-can@...r.kernel.org, linux-afs@...ts.infradead.org,
        kvm@...r.kernel.org,
        "Gustavo A . R . Silva" <gustavo@...eddedor.com>
Subject: Re: [PATCH] docs: use flexible array members, not zero-length

On Sat, 28 Sep 2019 01:16:39 -0600, Jonathan Corbet <corbet@....net> wrote:
> On Fri, 27 Sep 2019 16:29:27 +0200
> Stephen Kitt <steve@....org> wrote:
> > diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst
> > index 4d565d202ce3..24ce50fc1fc1 100644
> > --- a/Documentation/bpf/btf.rst
> > +++ b/Documentation/bpf/btf.rst
> > @@ -670,7 +670,7 @@ func_info for each specific ELF section.::
> >          __u32   sec_name_off; /* offset to section name */
> >          __u32   num_info;
> >          /* Followed by num_info * record_size number of bytes */
> > -        __u8    data[0];
> > +        __u8    data[];
> >       };  
> 
> I only checked this one, but found what I had expected: the actual
> definition of this structure (found in tools/lib/bpf/libbpf_internal.h)
> says "data[0]".  We can't really make the documentation read the way we
> *wish* the source would be, we need to document reality.
> 
> I'm pretty sure that most of the other examples will be the same.

Aargh, yes, of course, thanks for checking! I was locked in a “prescriptive”
documentation mode, but this type of documentation has to be descriptive
since it’s documenting shared structures, not structures which developers
have to write.

> If you really want to fix these, the right solution is to fix the offending
> structures — one patch per structure — in the source, then update the
> documentation to match the new reality.

Yes. I have a Coccinelle script which takes care of the code, but it doesn’t
work for docs ;-).

Wouldn’t it be better to update the docs simultaneously in each patch which
fixes a structure? Or is that unworkable with current development practices?

Regards,

Stephen

Content of type "application/pgp-signature" skipped