Re: FW: [PATCH] [RFC] newlib: libc: start manual appendix to hold various ABI constants

>
> -----Original Message-----
> From: Mike Frysinger <[email protected]>
> Sent: Wednesday, December 27, 2023 2:25 AM
> To: [email protected]
> 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