Re: [PATCH v3] Many pages: Document fixed-width types with ISO C naming

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hi Linus,

(Oops, I mistyped you name in my previous reply; I'm on a roll for funny typos this week it seems)

On 8/25/22 09:42, Linus Torvalds wrote:
On Thu, Aug 25, 2022 at 12:20 AM Alejandro Colomar
<alx.manpages@xxxxxxxxx> wrote:

This patch is not about kernel, but about the section 2 and 3 manual
pages, which are directed towards user-space readers most of the time.

They are about the types to the kernel interfaces. Those types that
the kernel defines and exposes.

And the kernel type in question looks like this:

         struct { /* anonymous struct used by BPF_PROG_LOAD command */
                 __u32           prog_type;      /* one of enum bpf_prog_type */
                 __u32           insn_cnt;
                 __aligned_u64   insns;
                 __aligned_u64   license;

because the kernel UAPI header wants to

  (a) work whether or not <stdint.h> was included

These days, (a) is more of a theoretical thing, since programs avoiding C99 <stdint.h> will have a hard time.


  (b) doesn't want to include <stdint.h> so as to not pollute the namespace

  (c) actually wants to use our special types

I quoted a few more fields for that (c) reason: we've had a long
history of getting the user space API wrong due to strange alignment
issues, where 32-bit and 64-bit targets had different alignment for
types. So then we ended up with various compat structures to translate
from one to the other because they had all the same fields, but
different padding.

This happened a few times with the DRM people, and they finally got
tired of it, and started using that "__aligned_u64" type, which is
just the same old __u64, but explicitly aligned to its natural
alignment.

So these are the members that the interface actually uses.

If you document those members, wouldn't it be good to have that
documentation be actually accurate?

Honestly, I don't think it makes a *huge* amount of difference, but
documentation that doesn't actually match the source of the
documentation will just confuse somebody in the end. Somebody will go
"that's not right", and maybe even change the structure definitions to
match the documentation.

Which would be wrong.

Now, you don't have to take the kernel uapi headers. We *try* to make
those usable as-is, but hey, there has been problems in the past, and
it's not necessarily wrong to take the kernel header and then munge it
to be "appropriate" for user space.

So I guess you can just make your own structures with the names and
syntax you want, and say "these are *my* header files, and *my*
documentation for them".

That's fine. But I'm not surprised if the kernel maintainer then goes
"no, that's not the interface I agreed to" if only because it's a pain
to verify that you got it all right. Maybe it was all trivial and
automated and there can be no errors, but it's still a "why is there a
different copy of this complicated interface".

If you really want to describe things to people, wouldn't it be nicer
to just say "there's a 32-bit unsigned 'prog_type' member" and leave
it at that?

Do you really want to enforce your opinion of what is prettier on the
maintainer that wrote that thing, and then argue with him when he
doesn't agree?

You convinced me. The man-pages will document the types exactly as they are in kernel. It's just simpler.

As the patch was recently reverted after Greg asked me to do, I'll keep it that way. I guess this closes the man-pages discussion.

I'd still like to see the kernel types be API-compatible with the user-space ones, for which there's a patch around, and also making the <stdint.h> types be builtind could also be nice. Let's see if that works out.

Cheers,

Alex

--
Alejandro Colomar
<http://www.alejandro-colomar.es/>

Attachment: OpenPGP_signature
Description: OpenPGP digital signature


[Index of Archives]     [Linux Samsung SoC]     [Linux Rockchip SoC]     [Linux Actions SoC]     [Linux for Synopsys ARC Processors]     [Linux NFS]     [Linux NILFS]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]


  Powered by Linux