BPF Archive on lore.kernel.org
 help / color / Atom feed
From: Zack Weinberg <zackw@panix.com>
To: Daniel Borkmann <daniel@iogearbox.net>
Cc: "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>,
	Greg KH <gregkh@linuxfoundation.org>,
	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>,
	David Miller <davem@davemloft.net>
Subject: Re: [RFC v2] bpf.2: Use standard types and attributes
Date: Tue, 4 May 2021 16:33:24 -0400
Message-ID: <CAKCAbMidJ=UhsMumDcwiqvkGEG5SROPnv=OA379w_=0dZk5W5g@mail.gmail.com> (raw)
In-Reply-To: <8a184afe-14b7-ed15-eb6a-960ea05251d1@iogearbox.net>

On Tue, May 4, 2021 at 4:06 PM Daniel Borkmann <daniel@iogearbox.net> 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

  parent 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 ` [RFC] " 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)
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 [this message]
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='CAKCAbMidJ=UhsMumDcwiqvkGEG5SROPnv=OA379w_=0dZk5W5g@mail.gmail.com' \
    --to=zackw@panix.com \
    --cc=David.Laight@aculab.com \
    --cc=alexei.starovoitov@gmail.com \
    --cc=alx.manpages@gmail.com \
    --cc=bpf@vger.kernel.org \
    --cc=daniel@iogearbox.net \
    --cc=davem@davemloft.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 \
    /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