From: Alejandro Colomar <alx.manpages@gmail.com> To: Linus Torvalds <torvalds@linux-foundation.org> Cc: Alexei Starovoitov <alexei.starovoitov@gmail.com>, Alex Colomar <alx@kernel.org>, Alexei Starovoitov <ast@kernel.org>, linux-man <linux-man@vger.kernel.org>, Greg Kroah-Hartman <gregkh@linuxfoundation.org>, Daniel Borkmann <daniel@iogearbox.net>, Zack Weinberg <zackw@panix.com>, LKML <linux-kernel@vger.kernel.org>, glibc <libc-alpha@sourceware.org>, GCC <gcc-patches@gcc.gnu.org>, bpf <bpf@vger.kernel.org>, LTP List <ltp@lists.linux.it>, Linux API <linux-api@vger.kernel.org>, linux-arch <linux-arch@vger.kernel.org>, David Laight <David.Laight@aculab.com>, Joseph Myers <joseph@codesourcery.com>, Florian Weimer <fweimer@redhat.com>, Cyril Hrubis <chrubis@suse.cz>, David Howells <dhowells@redhat.com>, Arnd Bergmann <arnd@arndb.de>, Rich Felker <dalias@libc.org>, Adhemerval Zanella <adhemerval.zanella@linaro.org>, Michael Kerrisk <mtk.manpages@gmail.com> Subject: Re: [PATCH v3] Many pages: Document fixed-width types with ISO C naming Date: Thu, 25 Aug 2022 09:59:31 +0200 [thread overview] Message-ID: <ee51a03e-0cc7-06a6-2ae9-e68af02e891f@gmail.com> (raw) In-Reply-To: <CAHk-=wgSx8O0=p18C1aQuH4Gw7xmKujBKMEiSitCA7oG2h6WLg@mail.gmail.com> [-- Attachment #1.1: Type: text/plain, Size: 4000 bytes --] 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@gmail.com> 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 #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --]
WARNING: multiple messages have this Message-ID (diff)
From: Alejandro Colomar <alx.manpages@gmail.com> To: Linus Torvalds <torvalds@linux-foundation.org> Cc: linux-man <linux-man@vger.kernel.org>, Rich Felker <dalias@libc.org>, Alexei Starovoitov <ast@kernel.org>, David Howells <dhowells@redhat.com>, Alexei Starovoitov <alexei.starovoitov@gmail.com>, Joseph Myers <joseph@codesourcery.com>, linux-arch <linux-arch@vger.kernel.org>, Zack Weinberg <zackw@panix.com>, Daniel Borkmann <daniel@iogearbox.net>, Alex Colomar <alx@kernel.org>, Michael Kerrisk <mtk.manpages@gmail.com>, Arnd Bergmann <arnd@arndb.de>, GCC <gcc-patches@gcc.gnu.org>, LTP List <ltp@lists.linux.it>, glibc <libc-alpha@sourceware.org>, Greg Kroah-Hartman <gregkh@linuxfoundation.org>, LKML <linux-kernel@vger.kernel.org>, David Laight <David.Laight@aculab.com>, Adhemerval Zanella <adhemerval.zanella@linaro.org>, Linux API <linux-api@vger.kernel.org>, bpf <bpf@vger.kernel.org> Subject: Re: [LTP] [PATCH v3] Many pages: Document fixed-width types with ISO C naming Date: Thu, 25 Aug 2022 09:59:31 +0200 [thread overview] Message-ID: <ee51a03e-0cc7-06a6-2ae9-e68af02e891f@gmail.com> (raw) In-Reply-To: <CAHk-=wgSx8O0=p18C1aQuH4Gw7xmKujBKMEiSitCA7oG2h6WLg@mail.gmail.com> [-- Attachment #1.1.1: Type: text/plain, Size: 4000 bytes --] 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@gmail.com> 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 #1.2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] [-- Attachment #2: Type: text/plain, Size: 60 bytes --] -- Mailing list info: https://lists.linux.it/listinfo/ltp
next prev parent reply other threads:[~2022-08-25 7:59 UTC|newest] Thread overview: 68+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-04-23 23:06 [RFC] bpf.2: Use standard types and attributes Alejandro Colomar 2021-04-23 23:20 ` 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-04-26 17:19 ` Joseph Myers 2021-04-26 17:46 ` Alejandro Colomar (man-pages) 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) 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 ` [LTP] [PATCH v3] Many pages: Document fixed-width types with ISO C naming Alejandro Colomar 2022-08-24 18:55 ` Alejandro Colomar 2022-08-24 22:40 ` Alexei Starovoitov 2022-08-24 22:40 ` [LTP] " Alexei Starovoitov 2022-08-24 23:36 ` Alejandro Colomar 2022-08-24 23:36 ` [LTP] " Alejandro Colomar 2022-08-25 0:52 ` Linus Torvalds 2022-08-25 0:52 ` Linus Torvalds 2022-08-25 7:20 ` [LTP] " Alejandro Colomar 2022-08-25 7:20 ` Alejandro Colomar 2022-08-25 7:28 ` Xi Ruoyao 2022-08-25 7:28 ` [LTP] " Xi Ruoyao via ltp 2022-08-25 7:48 ` Alejandro Colomar 2022-08-25 7:48 ` Alejandro Colomar 2022-08-25 8:09 ` Xi Ruoyao 2022-08-25 8:09 ` [LTP] " Xi Ruoyao via ltp 2022-08-25 7:42 ` Linus Torvalds 2022-08-25 7:42 ` Linus Torvalds 2022-08-25 7:59 ` Alejandro Colomar [this message] 2022-08-25 7:59 ` Alejandro Colomar 2022-08-25 5:57 ` [LTP] " Greg Kroah-Hartman 2022-08-25 5:57 ` Greg Kroah-Hartman 2022-08-25 6:41 ` Florian Weimer 2022-08-25 6:41 ` [LTP] " Florian Weimer 2022-08-25 7:27 ` Linus Torvalds 2022-08-25 7:27 ` [LTP] " Linus Torvalds 2022-08-25 14:38 ` Joseph Myers 2022-08-25 14:38 ` [LTP] " Joseph Myers 2022-08-25 15:01 ` David Laight 2022-08-25 15:01 ` David Laight 2022-08-25 15:37 ` Joseph Myers 2022-08-25 15:37 ` [LTP] " Joseph Myers 2022-08-25 16:43 ` Linus Torvalds 2022-08-25 16:43 ` Linus Torvalds 2022-08-25 7:44 ` [LTP] " Alejandro Colomar 2022-08-25 7:44 ` Alejandro Colomar 2022-08-25 8:04 ` [LTP] " 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=ee51a03e-0cc7-06a6-2ae9-e68af02e891f@gmail.com \ --to=alx.manpages@gmail.com \ --cc=David.Laight@aculab.com \ --cc=adhemerval.zanella@linaro.org \ --cc=alexei.starovoitov@gmail.com \ --cc=alx@kernel.org \ --cc=arnd@arndb.de \ --cc=ast@kernel.org \ --cc=bpf@vger.kernel.org \ --cc=chrubis@suse.cz \ --cc=dalias@libc.org \ --cc=daniel@iogearbox.net \ --cc=dhowells@redhat.com \ --cc=fweimer@redhat.com \ --cc=gcc-patches@gcc.gnu.org \ --cc=gregkh@linuxfoundation.org \ --cc=joseph@codesourcery.com \ --cc=libc-alpha@sourceware.org \ --cc=linux-api@vger.kernel.org \ --cc=linux-arch@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=linux-man@vger.kernel.org \ --cc=ltp@lists.linux.it \ --cc=mtk.manpages@gmail.com \ --cc=torvalds@linux-foundation.org \ --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: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.