BPF Archive on lore.kernel.org
 help / color / Atom feed
From: David Laight <David.Laight@ACULAB.COM>
To: 'Zack Weinberg' <zackw@panix.com>
Cc: Alexei Starovoitov <alexei.starovoitov@gmail.com>,
	Alejandro Colomar <alx.manpages@gmail.com>,
	bpf <bpf@vger.kernel.org>, linux-man <linux-man@vger.kernel.org>,
	"gcc-patches@gcc.gnu.org" <gcc-patches@gcc.gnu.org>,
	"libc-alpha@sourceware.org" <libc-alpha@sourceware.org>,
	"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>,
	LKML <linux-kernel@vger.kernel.org>
Subject: RE: [RFC] bpf.2: Use standard types and attributes
Date: Sun, 25 Apr 2021 21:09:21 +0000
Message-ID: <600f0f5de9ff4bc887eec42d38113a8c@AcuMS.aculab.com> (raw)
In-Reply-To: <CAKCAbMgJBRKc+kszT-foDtOQC6Q1veOuxC_a1aX_Qt4PTCpEkg@mail.gmail.com>

From: Zack Weinberg
> Sent: 25 April 2021 20:17
> 
> On Sat, Apr 24, 2021 at 4:43 PM David Laight via Libc-alpha
> <libc-alpha@sourceware.org> wrote:
> > From: Alexei Starovoitov
> > > On Fri, Apr 23, 2021 at 4:15 PM Alejandro Colomar <alx.manpages@gmail.com> 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.

Depends, if the man page defines the structure - it needs to
contain its definition.
If theory the man page ought to be the definition, and the code
do what the man page says happens.

An alternative is for the man page to say that the structure
contains some fields - without prescribing the order, or
stopping the implementation adding additional fields (or even
changing the actual numeric type).
This is more common in the standards documents.
IMHO The Linux pages really ought to say how linux does things.
(With notes about portability.)

	David

-
Registered Address Lakeside, Bramley Road, Mount Farm, Milton Keynes, MK1 1PT, UK
Registration No: 1397386 (Wales)

  reply index

Thread overview: 27+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <20210423230609.13519-1-alx.manpages@gmail.com>
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 [this message]
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

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=600f0f5de9ff4bc887eec42d38113a8c@AcuMS.aculab.com \
    --to=david.laight@aculab.com \
    --cc=alexei.starovoitov@gmail.com \
    --cc=alx.manpages@gmail.com \
    --cc=bpf@vger.kernel.org \
    --cc=gcc-patches@gcc.gnu.org \
    --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

BPF Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/bpf/0 bpf/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 bpf bpf/ https://lore.kernel.org/bpf \
		bpf@vger.kernel.org
	public-inbox-index bpf

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.bpf


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git