From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wm1-x32b.google.com (mail-wm1-x32b.google.com [IPv6:2a00:1450:4864:20::32b]) by sourceware.org (Postfix) with ESMTPS id D159F3858C52 for ; Sat, 30 Dec 2023 01:17:49 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org D159F3858C52 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gmail.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org D159F3858C52 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=2a00:1450:4864:20::32b ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1703899076; cv=none; b=sRZI9lSiCRQEA3vobrSda6fXrEh1TtpBwfTpnDZmtNUaeV3vg58knv4yF0HjDH4yVl8FHsItBkb/qimfEIOEjBbNImoPVBiUOdmO9p/ERoCDem7JRYkHMhEbpF+ZFew2MFwnX3hQM/OEN62OVCkiWpDMc1cLHQB+/osjQ5Wyfj4= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1703899076; c=relaxed/simple; bh=YauNP/q5wIw2ty7WZropYsXK6Y6ATTfurbKkRwvjVOg=; h=DKIM-Signature:MIME-Version:From:Date:Message-ID:Subject:To; b=gQK3mLtMs0CFttYDnJ6Vu5gRTsWGn42aIsswRe2r97zHx9jtR9V2p4C0v2pH/4GmcMhDjoFXt5caQ+FIEvzvKLB4Wzwukj8hchbvpXXNslUjJDGKovj/c6wbuKO6UA2mDGrzDfRtDDc/nxkKLll+JOm9W/Xo6GfHlHCPeNdB++o= ARC-Authentication-Results: i=1; server2.sourceware.org Received: by mail-wm1-x32b.google.com with SMTP id 5b1f17b1804b1-40d4103aed7so88983425e9.3 for ; Fri, 29 Dec 2023 17:17:49 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1703899068; x=1704503868; darn=sourceware.org; h=to:subject:message-id:date:from:in-reply-to:references:mime-version :from:to:cc:subject:date:message-id:reply-to; bh=7o7noXGIf8QOYlQryhcleQU4Hshl4C5D+k7sQZvThmA=; b=ac3ASiqW1FTzcskevKvC6NreL1qtEI9YAOkpfdF1rC5bHzlY3Z7ArijxBUYNUkKyIN FLFHel9/keUZMHPITWJtxbvMkg6GdkAJ+mfICeIJBYB9NLHr0Ob2XHdUHTp8L5CpdcbT +KAyAGX7mzmShgmg79cgCKbY/8dCv+w+16CTI3KZ0eGprYh0wFDzZtxJWG9t37N9375W 53m7Tr6/b0WIA7pgA9t71I42echY0uIbBbrt0C2ILZe4cfLtwfSrnOE4wbEDkXIH/hG9 5gbJA7/ipaaw0A3pq2sc5/e4/wFebOiKTbuWq/x0ekj//vFMteC9VGoYeTGXCt9O/y9f HsTg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1703899068; x=1704503868; h=to:subject:message-id:date:from:in-reply-to:references:mime-version :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=7o7noXGIf8QOYlQryhcleQU4Hshl4C5D+k7sQZvThmA=; b=qb2tjN/6f7ZIeF0DFXc6JMOgyrmeUkExFRzQiJi7JNpXrEGtkhmRa89QvIHTOnPqcp Xf843XYWfAS5auSjoUfoezn7mPmZElwS50iwf6S0Bc/a6jRRPbWN4NYH7R9zBd2BFzco AFQrf5cOT+U2i98/M90oCmfDvBMS2joS+okxFw0yrU9hb6lLmPYNvg2UmlTUDQov/Bit aCmHqjyWkIzg04Xl4MkiRBZLmL/7SR5Md3URACspkwtJJl6/rYO1V3vICwcL4rCwFpBC cNq9atD2S08abXkShkegTaDV6htK4EWJ+JTK3/6t/66KYpe9/zRVTNWQ6MmafOkiAAqu ZuhA== X-Gm-Message-State: AOJu0YzOKLsdOfjb8mZWNz+4LSBVpvpmcJI4qLfMu4KjPjzPzuBv3lj7 7VWvooUIa6/6ZTHM06bY0YGFYtx+Zvmjuoy9w3X+1BCyHurY X-Google-Smtp-Source: AGHT+IGSQdveCOOvL9CAP+5t8khPWeRRx3NmDehXjmcb2C7Jj9nFTS7fo3K+ZGb4uEZx+6vURIJCY6GyrnNWwebU3go= X-Received: by 2002:a05:600c:470d:b0:40d:60c3:3d53 with SMTP id v13-20020a05600c470d00b0040d60c33d53mr2551232wmo.103.1703899068217; Fri, 29 Dec 2023 17:17:48 -0800 (PST) MIME-Version: 1.0 References: <20231227072512.17179-1-vapier@gentoo.org> In-Reply-To: From: C Howland Date: Fri, 29 Dec 2023 20:17:36 -0500 Message-ID: Subject: Re: FW: [PATCH] [RFC] newlib: libc: start manual appendix to hold various ABI constants To: newlib@sourceware.org Content-Type: multipart/alternative; boundary="000000000000b1bc89060dafeab3" X-Spam-Status: No, score=-7.9 required=5.0 tests=BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,GIT_PATCH_0,HTML_MESSAGE,RCVD_IN_DNSWL_NONE,SPF_HELO_NONE,SPF_PASS,TXREP,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: --000000000000b1bc89060dafeab3 Content-Type: text/plain; charset="UTF-8" > > -----Original Message----- > From: Mike Frysinger > Sent: Wednesday, December 27, 2023 2:25 AM > To: newlib@sourceware.org > Subject: [PATCH] [RFC] newlib: libc: start manual appendix to hold various > ABI constants > > The newlib errno values end up being exposed way beyond newlib itself, so > it can be helpful to have a reference of the names & values of them all. > When using a GNU stack, the errno values might be shared across all of them > without any translation layers. > > ... > > Start an appendix in the libc manual to hold these constants. These pages > are automatically generated using the preprocessor and a script from the > GNU simulator project. If people are amenable to this direction, I can > port that script over to newlib & strip it down, and also add a few more > appendix chapters for other important ABI constants (e.g. signals). > I won't comment on whether adding this is a good idea or not as I don't meet any of the stated use cases. But here are a few thoughts on the details of it assuming others like the addition. Given the stated purpose it sounds like mapping files might want to be made for some of the scenarios mentioned. For something like that I'd think most people would want to start with the source code (as opposed to copying from the manual). With this in mind, adding the Newlib source file path as supplementary information to the values in the manual might make sense as an additional aid. Thinking a step beyond the stated purpose of making the values available in the manual for mapping purposes, in a bigger-picture view (it is a manual) would it make sense to preserve the descriptive comments in the source, copying them to the manual, too? (Without seeing the script mechanism being used I can't tell how easy or hard that might be to add.) > ... > +@node Newlib ABI > +@appendix Newlib ABI > +These are the various constants that newlib is built upon. They might > +be exposed in error messages that people have to manually decode, or > +they might be passed to other layers (e.g. when calling OS support > functions via libgloss). > + > It might be better to enhance the wording here a little. Some thoughts to that end in "" below. Additionally, the word choice "common" can be confusing, as it can lead one to think that those values are in common with all architectures and that deviations from them are listed in the supplementary sections. I wondered this while reading and had to look through to see that this is not the case (which led to my first suggested addition below). Maybe say "common/default", or "default" instead? > +@node Newlib ABI Errno > +@section Errno Values > +Most architectures use the common set of errno values. Only a minor > +few deviate from them. > "Each set of errno values presented is standalone, independent of every other set. Unless there is a specific set for a given architecture, refer to the 'Common Errno Values' subsection. > + > +@subsection Common Errno Values > "Values in this subsection apply to any architecture not specifically named for a different errno value set." > +@lowersections > +@include errno/constants.tex > +@raisesections > + > +@subsection CRIS Errno Values > "Values in this subsection apply only for the CRIS architecture." > +@lowersections > +@include machine/cris/constants-errno.tex @raisesections > + > +@subsection SPU Errno Values > "Values in this subsection apply only for the SPU architecture." > ... > diff --git a/newlib/libc/machine/cris/Makefile.inc > b/newlib/libc/machine/cris/Makefile.inc > index f1864e352fb6..10d35ca10ed3 100644 > --- a/newlib/libc/machine/cris/Makefile.inc > +++ b/newlib/libc/machine/cris/Makefile.inc > @@ -11,3 +11,6 @@ toollib_LIBRARIES += %D%/libic.a > %D%/libc_a-memset.o \ > %D%/libc_a-memmove.o \ > %D%/libc_a-libcdtor.o > ... > +@c This file is machine generated by gennltvals.py. > + > +@subsection Sorted by name > ... > +@end multitable > + > +@subsection Sorted by value > Given today's reality of no printed (vs. electronic) manuals (maybe a rare person that might print a copy), is it worth bothering to present both name and number sorted lists? (People will just electronically search, making the multiple presentation of essentially no added value.) Just choose 1 and do that only? (The cost of doing it is low, and choosing numeric or name might be tricky to decide. But dropping to 1 would reduce electronic search clutter of having the same thing found twice per subsection. Already will be a little bit distracting to have the common/cris/spu sections, twice as bad if each lists both values twice.) Craig --000000000000b1bc89060dafeab3--