Re: [RFC] bpf.2: Use standard types and attributes
On Sun, Apr 25, 2021 at 12:52 PM Alexei Starovoitov via Libc-alpha wrote: > On Sat, Apr 24, 2021 at 10:56 AM Alejandro Colomar (man-pages) > wrote: > > > > Hello Alexei, > > > > On 4/24/21 1:20 AM, Alexei Starovoitov wrote: > > > Nack. > > > The man page should describe the kernel api the way it is in .h file. > > > > Why? > > Because man page must describe the linux uapi headers the way they > are installed in the system and not invent alternative implementations. > The users will include those .h with __u32 and will see them in their code. > Man page saying something else is a dangerous lie. Why do you consider it _dangerous_ for the manpages to replace __u32 with uint32_t, when we know by construction that the two types will always be the same? Alejandro's preference for the types standardized by ISO C seems perfectly reasonable to me for documentation; people reading the documentation can be expected to already know what they mean, unlike the Linux-specifc __[iu]NN types. Also, all else being equal, documentation should avoid use of symbols in the ISO C reserved namespace. If anything I would argue that it is the uapi headers that should be changed, to use the types. zw
Re: [RFC] bpf.2: Use standard types and attributes
On Sat, Apr 24, 2021 at 4:43 PM David Laight via Libc-alpha wrote: > From: Alexei Starovoitov > > On Fri, Apr 23, 2021 at 4:15 PM Alejandro Colomar > > wrote: ... > > > Some pages also document attributes, using GNU syntax > > > '__attribute__((xxx))'. Update those to use the shorter and more > > > portable C2x syntax, which hasn't been standardized yet, but is > > > already implemented in GCC, and available through either --std=c2x > > > or any of the --std=gnu... options. .. > And the code below is no more portable that a #pragma'. > It is probably worse than __attribute__((aligned(8))) > +uint64_t [[gnu::aligned(8)]] value; > The standards committee are smoking dope again. > At least the '__aligned_u64 value;' form stands a reasonable > chance of being converted by cpp into whatever your compiler supports. Is it actually necessary to mention the alignment overrides at all in the manpages? They are only relevant to people working at the level of physical layout of the data in RAM, and those people are probably going to have to consult the header file anyway. zw
Re: [RFC v2] bpf.2: Use standard types and attributes
On Tue, May 4, 2021 at 12:06 PM Greg KH wrote: > On Tue, May 04, 2021 at 05:53:29PM +0200, Alejandro Colomar (man-pages) wrote: > > On 5/4/21 4:24 PM, Greg KH wrote: > > > I agree, the two are not the same type at all, this change should not be > > > accepted. > > > > I get that in the kernel you don't use the standard fixed-width types (with > > some exceptions), probably not to mess with code that relies on > > not being included (I hope there's not much code that relies on this in > > 2021, but who knows). > > > > But, there is zero difference between these types, from the point of view of > > the compiler. There's 100% compatibility between those types, and you're > > able to mix'n'match them. See some example below. ... > There's a very old post from Linus where he describes the difference > between things like __u32 and uint32_t. They are not the same, they > live in different namespaces, and worlds, and can not always be swapped > out for each other on all arches. > > Dig it up if you are curious, but for user/kernel apis you HAVE to use > the __uNN and can not use uintNN_t variants, so don't try to mix/match > them, it's good to just follow the kernel standard please. ... > Nacked-by: Greg Kroah-Hartman Speaking from the C library's perspective, I'm going to push back pretty hard on this NAK, for several reasons. First, this is a proposed change to the manpages, not the headers themselves. Manpage documentation of C structs is *not* expected to match the actual declaration in the headers. The documented field type is usually assignment-compatible with the actual type, but not always. There's no guarantee whatsoever that the fields are in the same order as the header, or that the listed set of fields is complete. I would say that as long as any value of type __u32 can be stored in a variable of type uint32_t without data loss, and vice versa, there is no reason why manpages should *have to* use __u32 in preference to uint32_t, and that in the absence of such a reason, the standard type should be used. Second, it's true that __u32 and uint32_t are in different namespaces, and it may well be necessary for uapi headers to use the __uNN names in order to preserve the C standard's distinction between the program and the implementation, but that's *not* a reason for documentation aimed at writers of user-space programs to use the __uNN names. In fact, it is exactly the opposite! User space program authors should, all else equal, be *discouraged* from using the __uNN names, and avoiding their use in manpages is one way to do that. Third, if there does in fact exist a situation where __uNN and uintNN_t are *not* assignment compatible, THAT IS A BUG IN THE KERNEL. Frankly, it would be such a catastrophic bug that I think Linus has to have been *wrong*. We would have noticed the problems long ago if he were right. I'm going to have to ask you to produce hard evidence for your claim that __uNN and uintNN_t are not (always) assignment compatible, and hard evidence why that can't be fixed within the kernel, or else withdraw your objection. zw
Re: [RFC v2] bpf.2: Use standard types and attributes
On Tue, May 4, 2021 at 4:06 PM Daniel Borkmann wrote:
> > I'm trying to clarify the manual pages as much as possible, by using
> > standard conventions and similar structure all around the pages. Not
> > everyone understands kernel conventions. Basically, Zack said very much
> > what I had in mind with this patch.
>
> But then are you also converting, for example, __{le,be}{16,32,64} to plain
> uint{16,32,64}_t in the man pages and thus removing contextual information
> (or inventing new equivalent types)?
>
> What about other types exposed to user space like __sum16, __wsum, or __poll_t
> when they are part of a man page, etc?
Fields that are specifically in some endianness that isn't
(necessarily) the CPU's _should_ be documented as such in the manpage,
but I dunno if __{le,be}{16,32,64} as a type name is the ideal way to
do it. There is no off-the-shelf notation for this as far as I know.
I do not know what __sum16, __wsum, and __poll_t are used for, but I
want to remind everyone again that the kernel's concerns are not
necessarily user space's concerns and the information that should
appear in the manpages is the information that is most relevant to
user space programmers.
zw
Re: [RFC] Add stdckdint.h header for C23
On Wed, Jun 14, 2023, at 10:52 AM, Joseph Myers wrote: > On Tue, 13 Jun 2023, Paul Eggert wrote: > >> > There is always the possibility to have the header co-owned by both >> > the compiler and C library, limits.h style. Just >> > #if __has_include_next() >> > # include_next >> > #endif >> >> I don't see how you could implement >> __has_include_next() for arbitrary non-GCC compilers, >> which is what we'd need for glibc users. For glibc internals we can >> use "#include_next" more readily, since we assume a new-enough GCC. >> I.e. we could do something like this: > > Given the possibility of library functions being included in > in future standard versions, it seems important to look > at ways of splitting responsibility for the header between the > compiler and library, whether with __has_include_next, or compiler > version conditionals, or some other such variation. limits.h is a horrible mess, with both the compiler and the library trying to get the last word, and I don't think we should take it as a model. I suggest a better model is GCC 12's stdint.h, where the compiler provides "stdint-gcc.h" that's used *only* in freestanding mode, and a wrapper header that defers to the C library (using #include_next, which is safe in GCC-provided headers) when __STDC_HOSTED__ is defined; meanwhile, glibc's stdint.h doesn't look for compiler-provided headers at all. In this case it sounds like glibc needs the compiler to provide some of the definitions, and I suggest this should be done via private predefined macros, in the mode of __INTx_TYPE__ and friends. zw
