Received: by 2002:a05:6358:45e:b0:b5:b6eb:e1f9 with SMTP id 30csp367200rwe; Thu, 25 Aug 2022 01:34:31 -0700 (PDT) X-Google-Smtp-Source: AA6agR7yjycY3yypzP9MhPN6MILKWNN6TNabju55RWulBDNCopKMV4y/hBmdWm0l11AOWrufvX1m X-Received: by 2002:a05:6a00:14c6:b0:536:f974:1bf7 with SMTP id w6-20020a056a0014c600b00536f9741bf7mr3068627pfu.27.1661416471040; Thu, 25 Aug 2022 01:34:31 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1661416471; cv=none; d=google.com; s=arc-20160816; b=Krw1xURs+hNVddZd5+x08nJZ9xIOWPnVgdzZkxBMXiA7J+pdGBJZd6Y6G0OkB0l1cq esoL7qiZBNkadnIrCP+9NXSFpgIeElZYOXYqEzp0538yT/uYs+H+5MF6fn6TwvLYSqvN i//M5hBgx1Cvr5pnMpGH73NmEVDzMWh6DPuy4Apx2Mn23VxEKRqEw7yVcylrPWnUdnDS y9UPnuyYar3Ez3O6S0f8GwjLiIEXmV1hRxsX+8rMl7IygDghxhnbLdtKfQzCZmQd5p8p 18UOemcO7sJHT3h6XzoR8xOpJqwTLIy1IzVQoTgvo2Cx5fn4Wx6pkgutRv6NdJThft4p YVAw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:cc:to:subject:message-id:date:from:in-reply-to :references:mime-version:dkim-signature; bh=pTSOf4yZBT6vxC8cWVxq54me3auAZtvDfhz2BczVtgE=; b=D9bCVezgwerhPWFdmH2h8o7eRn2fePM+Pm+iJnDq/oB+u5HTqyZDg2vtjHRtxOnnAV RkTUAjrxDYSJc/w6mtUoEL3Lvsdd5avnFZKUu+qawFLhEa3Mx5L+KfwiC8HoygOXaia5 QqlNoeX3fOFkzJHrVuH0yuZPlYuvZaIMMqKxwwFX5u2amILREal6l+un6O/Q/djSbJ4y V4cmlGFUx2CrdpaadLkMKgcenmj5xymUfo3iHZqFwmFjweLezXDmEg9BLYhHi7p6zpCX mByI70D95MwpIC0EISof5BFhLrb0kEdbivpPisIVrDHV+bHn1hokQoMR8oh3Qbb8Y2J7 cl9A== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linux-foundation.org header.s=google header.b=Ig6BLIDs; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id u23-20020a63d357000000b0041c26d335f4si17576864pgi.678.2022.08.25.01.33.56; Thu, 25 Aug 2022 01:34:31 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@linux-foundation.org header.s=google header.b=Ig6BLIDs; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S238853AbiHYHnk (ORCPT + 99 others); Thu, 25 Aug 2022 03:43:40 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38174 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S238659AbiHYHnD (ORCPT ); Thu, 25 Aug 2022 03:43:03 -0400 Received: from mail-ed1-x52d.google.com (mail-ed1-x52d.google.com [IPv6:2a00:1450:4864:20::52d]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9F37EA2D97 for ; Thu, 25 Aug 2022 00:42:57 -0700 (PDT) Received: by mail-ed1-x52d.google.com with SMTP id 2so16955881edx.2 for ; Thu, 25 Aug 2022 00:42:57 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux-foundation.org; s=google; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc; bh=pTSOf4yZBT6vxC8cWVxq54me3auAZtvDfhz2BczVtgE=; b=Ig6BLIDsaP7fwO4f2tblxSV8D0IEZ23t5746evH4pnH6oehSyZT/w7P79opUL+FnmK po3y3tMhPtweDHchzB18ityI3jwyATZyGSAP0WrqhvTn5ohd5US0JPEFOAGmxSk5vacw sKRqdCKWOUSMVwQEX9dCud+27HCTh3lUtbqk4= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc; bh=pTSOf4yZBT6vxC8cWVxq54me3auAZtvDfhz2BczVtgE=; b=espDITqiAhgNxfW/LYlsBJwYKPZ00XG5yBy7F/YtE2nZ4BKgRa8uY8DaH0U30jaKpY PDWBthQoJOeLjFlPJYMYLxeZvAEqa3wDobMpdxeIA4V1+fW1k9t47XTV/Dd6byomSgdf GERiY1nzeLJHgYBkbIOji7B+Q+paRaEcCRhtdVzRHaim+fEnVJ5COGBue8pHzfNOThFh 3oPNBg8zEF5IV8Md9nQq0pK2hp+sxWB/mEbqBWFKyB69HPnblmLmMK6jNrEUDD2DPRNw m58SEID61FJ3Pt0bxrC3DJ83HEOFXreVNcR9+yAUc3zLfV6Im5OCGrDjCvKK+LRe/GOE YsbQ== X-Gm-Message-State: ACgBeo16lHoC3XvMGRXXQHUck0KHy68q0t4Sk+cMtj17g3g4zUv5cPeN goxzR9IX8MgM5yzcckAXDeXZsORrb8D6PGw/ikg= X-Received: by 2002:aa7:cfcb:0:b0:447:b4e5:22fb with SMTP id r11-20020aa7cfcb000000b00447b4e522fbmr1296542edy.190.1661413375759; Thu, 25 Aug 2022 00:42:55 -0700 (PDT) Received: from mail-wm1-f48.google.com (mail-wm1-f48.google.com. [209.85.128.48]) by smtp.gmail.com with ESMTPSA id bm2-20020a0564020b0200b0044604ad8b41sm4331256edb.23.2022.08.25.00.42.52 for (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 25 Aug 2022 00:42:54 -0700 (PDT) Received: by mail-wm1-f48.google.com with SMTP id h204-20020a1c21d5000000b003a5b467c3abso2180253wmh.5 for ; Thu, 25 Aug 2022 00:42:52 -0700 (PDT) X-Received: by 2002:a7b:c399:0:b0:3a5:f3fb:85e0 with SMTP id s25-20020a7bc399000000b003a5f3fb85e0mr1402129wmj.38.1661413369950; Thu, 25 Aug 2022 00:42:49 -0700 (PDT) MIME-Version: 1.0 References: <20210423230609.13519-1-alx.manpages@gmail.com> <20220824185505.56382-1-alx.manpages@gmail.com> <20d93962-538c-d2c9-1696-a1bdbffa87f8@gmail.com> In-Reply-To: <20d93962-538c-d2c9-1696-a1bdbffa87f8@gmail.com> From: Linus Torvalds Date: Thu, 25 Aug 2022 00:42:32 -0700 X-Gmail-Original-Message-ID: Message-ID: Subject: Re: [PATCH v3] Many pages: Document fixed-width types with ISO C naming To: Alejandro Colomar Cc: Alexei Starovoitov , Alex Colomar , Alexei Starovoitov , linux-man , Greg Kroah-Hartman , Daniel Borkmann , Zack Weinberg , LKML , glibc , GCC , bpf , LTP List , Linux API , linux-arch , David Laight , Joseph Myers , Florian Weimer , Cyril Hrubis , David Howells , Arnd Bergmann , Rich Felker , Adhemerval Zanella , Michael Kerrisk Content-Type: text/plain; charset="UTF-8" X-Spam-Status: No, score=-1.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, RCVD_IN_DNSWL_NONE,SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE, URIBL_BLOCKED autolearn=no autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Thu, Aug 25, 2022 at 12:20 AM Alejandro Colomar 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 was included (b) doesn't want to include 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? Linus