From: "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>
To: Zack Weinberg <zackw@panix.com>,
Greg KH <gregkh@linuxfoundation.org>,
Daniel Borkmann <daniel@iogearbox.net>
Cc: Alexei Starovoitov <alexei.starovoitov@gmail.com>,
"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>,
linux-man <linux-man@vger.kernel.org>,
LKML <linux-kernel@vger.kernel.org>,
glibc <libc-alpha@sourceware.org>, GCC <gcc-patches@gcc.gnu.org>,
bpf <bpf@vger.kernel.org>, Joseph Myers <joseph@codesourcery.com>,
David Laight <David.Laight@aculab.com>
Subject: Re: [RFC v2] bpf.2: Use standard types and attributes
Date: Tue, 4 May 2021 20:54:07 +0200 [thread overview]
Message-ID: <6740a229-842e-b368-86eb-defc786b3658@gmail.com> (raw)
In-Reply-To: <CAKCAbMg_eRCsD-HYmryL8XEuZcaM1Qdfp4XD85QKT6To+h3QcQ@mail.gmail.com>
Hi Greg, Daniel,
On 5/4/21 6:06 PM, Greg KH wrote:
> 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.
I found these:
* [RFC] Splitting kernel headers and deprecating __KERNEL__
<https://lore.kernel.org/lkml/Pine.LNX.4.58.0412140734340.3279@ppc970.osdl.org/T/>
* coding style
<https://lore.kernel.org/lkml/alpine.LFD.0.98.0706160840290.14121@woody.linux-foundation.org/>
* [patch] Small input fixes for 2.5.29
<https://lore.kernel.org/lkml/Pine.LNX.4.33.0207301417190.2051-100000@penguin.transmeta.com/T/>
I already knew the first one, and now found the other two. If there's
any other thread that is relevant, I couldn't find it.
The thing is, in all of those threads, the only reasons to avoid
<stdint.h> types in the kernel (at least, the only explicitly mentioned
ones) are (a bit simplified, but this is the general idea of those threads):
* Possibly breaking something in such a big automated change.
* Namespace collision with userspace (the C standard allows defining
uint32_t for nefarious purposes as long as you don't include <stdint.h>.
POSIX prohibits that, though)
* Uglier
But
* The manual pages only document the variable size and signedness by
using either '__u32' or 'uint32_t'. We state that the variable is an
unsigned integer of exactly 32 bits; nothing more and nothing less. It
doesn't specify that those types are defined in <linux/bpf.h> (or
whatever header a specific manual page uses). In fact, in uint32_t(3)
we clearly state the headers that shall provide the type. In the end,
the kernel will receive a 32 bit number. I'm not exactly sure about
what is wrong with this. Is there any magic in the kernel/user
interface beyond what the standard and the compiler define that I ignore?
* At that time (~2004), the C99 and POSIX.1-2001 standards were quite
young, and it was likely to find code that defined uint32_t. Currently,
it is hard to find something that compiles without C99, and even if C99
allows you to define uint32_t as long as you don't include <stdint.h>,
it would be really stupid to do so. And POSIX, which completely
prohibits defining uint32_t, is also very present in Linux and other
UNIX systems. So we can probably guarantee that using <stdint.h> in the
kernel wouldn't break anything. But yet this isn't trying to do so.
This is only about the manual pages.
I haven't read it in any of those threads, but suspect that the static
analyzer used for the kernel might use extra information from the
different 'u32'/'__u32' type names to do some extra checks. Does it?
> and can not always be swapped out for each other on all arches.
Really? 'uint32_t' is defined as "an unsigned integer type of a fixed
width of exactly 32 bits". How is that different from '[__]u32'?
Aren't the kernel types guaranteed to be unsigned integers of exactly 32
bits? AFAICT, they are 100% binary compatible; and if not, it's
probably a kernel bug.
Yes there are archs that don't provide 64 bit integers (I ignore if any
of the archs supported by Linux does though), but if an arch doesn't
provide 'uint64_t', it will neither be possible to have '__u64'.
[
uintN_t
Include: <stdint.h>. Alternatively, <inttypes.h>.
uint8_t, uint16_t, uint32_t, uint64_t
An unsigned integer type of a fixed width of ex‐
actly N bits, N being the value specified in its
type name. According to the C language standard,
they shall be capable of storing values in the
range [0, UINTN_MAX], substituting N by the appro‐
priate number.
According to POSIX, uint8_t, uint16_t, and
uint32_t are required; uint64_t is only required
in implementations that provide integer types with
width 64; and all other types of this form are op‐
tional.
] -- uint32_t(3)
>
> So consider this my:
>
> Nacked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
>
> as well.
Okay.
On 5/4/21 6:08 PM, Daniel Borkmann wrote:
>
> But what /problem/ is this really solving? Why bother to change this
/now/
> after so many years?! I think this is causing more confusion than solving
> anything, really. Moreover, what are you doing with all the
> __{le,be}{16,32,64}
> types in uapi? Anyway, NAK for bpf.2 specifically, and the idea
generally..
>
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.
Thanks for your reviews!
Regards,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
next prev parent reply other threads:[~2021-05-04 18:54 UTC|newest]
Thread overview: 46+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20210423230609.13519-1-alx.manpages@gmail.com>
2021-04-23 23:20 ` [RFC] bpf.2: Use standard types and attributes Alexei Starovoitov
2021-04-24 17:56 ` Alejandro Colomar (man-pages)
2021-04-25 16:52 ` Alexei Starovoitov
2021-04-25 19:12 ` Zack Weinberg
2021-04-24 20:43 ` David Laight
2021-04-25 19:16 ` Zack Weinberg
2021-04-25 21:09 ` David Laight
2021-05-04 11:05 ` [RFC v2] " Alejandro Colomar
2021-05-04 14:12 ` Alexei Starovoitov
2021-05-04 14:24 ` Greg KH
2021-05-04 15:53 ` Alejandro Colomar (man-pages)
2021-05-04 16:06 ` Greg KH
2021-05-04 18:37 ` Zack Weinberg
2021-05-04 18:54 ` Alejandro Colomar (man-pages) [this message]
2021-05-04 19:45 ` Florian Weimer
2021-05-04 19:59 ` Alejandro Colomar (man-pages)
2021-05-05 8:23 ` David Laight
2021-05-05 22:22 ` Joseph Myers
2021-05-04 20:06 ` Daniel Borkmann
2021-05-04 20:16 ` Alejandro Colomar (man-pages)
2021-05-04 20:33 ` Zack Weinberg
2021-05-04 21:23 ` Alexei Starovoitov
2021-05-15 19:01 ` [PATCH v3] " Alejandro Colomar
2021-05-16 9:16 ` Alejandro Colomar (man-pages)
2021-05-17 18:56 ` Daniel Borkmann
2021-05-21 11:12 ` Alejandro Colomar
2021-05-04 16:08 ` [RFC v2] " Daniel Borkmann
2022-08-24 18:55 ` [PATCH v3] Many pages: Document fixed-width types with ISO C naming Alejandro Colomar
2022-08-24 22:40 ` Alexei Starovoitov
2022-08-24 23:36 ` Alejandro Colomar
2022-08-25 0:52 ` Linus Torvalds
2022-08-25 7:20 ` Alejandro Colomar
2022-08-25 7:28 ` Xi Ruoyao
2022-08-25 7:48 ` Alejandro Colomar
2022-08-25 8:09 ` Xi Ruoyao
2022-08-25 7:42 ` Linus Torvalds
2022-08-25 7:59 ` Alejandro Colomar
2022-08-25 5:57 ` Greg Kroah-Hartman
2022-08-25 6:41 ` Florian Weimer
2022-08-25 7:27 ` Linus Torvalds
2022-08-25 14:38 ` Joseph Myers
2022-08-25 15:01 ` David Laight
2022-08-25 15:37 ` Joseph Myers
2022-08-25 16:43 ` Linus Torvalds
2022-08-25 7:44 ` Alejandro Colomar
2022-08-25 8:04 ` Alejandro Colomar
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=6740a229-842e-b368-86eb-defc786b3658@gmail.com \
--to=alx.manpages@gmail.com \
--cc=David.Laight@aculab.com \
--cc=alexei.starovoitov@gmail.com \
--cc=bpf@vger.kernel.org \
--cc=daniel@iogearbox.net \
--cc=gcc-patches@gcc.gnu.org \
--cc=gregkh@linuxfoundation.org \
--cc=joseph@codesourcery.com \
--cc=libc-alpha@sourceware.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-man@vger.kernel.org \
--cc=mtk.manpages@gmail.com \
--cc=zackw@panix.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).