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

[Corinna Vinschen]

On Dec 27 02:25, Mike Frysinger wrote:
> 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.
> 
> Consider:
> * user's code
> * GNU newlib (libc)
> * GNU libgloss (OS bindings)
> * GNU simulator (syscall handler)
> 
> When the user program tries to open a file that doesn't exist, it will
> call through newlib -> libgloss -> sim.  How is the error code handled ?
> The user program relies on newlib's ENOENT constant.  If newlib & libgloss
> don't agree on this value, then libgloss has to maintain a mapping of the
> different constants {"EAGAIN", NEWLIB_EAGAIN, LIBGLOSS_EAGAIN}.  No one
> does this of course -- libgloss just uses newlib's values directly.  If
> libgloss & the OS don't agree on this value, then libgloss again has to
> maintain a mapping of {"EAGAIN", NEWLIB_EAGAIN, OS_EAGAIN}.  No one does
> this with the GNU simulator -- it returns newlib's values directly.  The
> simulator definitely has to maintain a mapping of the target's EAGAIN
> values and whatever OS it is running on.  Having this be documented all
> the way down is important so people writing simulator ports know what
> values to use.
> 
> People implementing a minimal bootloader environment can easily be in the
> same boat -- they are trying to glue one world (e.g. Das U-Boot's machine
> independent API runtime) with another world (e.g. libgloss), and that will
> need to maintain the mapping of values in order for the programs to run
> unmodified.
> 
> 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).
> ---
>  newlib/Makefile.in                           | 281 +++++-----
>  newlib/libc/errno/Makefile.inc               |   3 +
>  newlib/libc/errno/constants.tex              | 349 ++++++++++++
>  newlib/libc/libc.texi                        |  26 +
>  newlib/libc/machine/cris/Makefile.inc        |   3 +
>  newlib/libc/machine/cris/constants-errno.tex | 541 +++++++++++++++++++
>  newlib/libc/machine/spu/Makefile.inc         |   3 +
>  newlib/libc/machine/spu/constants-errno.tex  | 517 ++++++++++++++++++
>  8 files changed, 1584 insertions(+), 139 deletions(-)
>  create mode 100644 newlib/libc/errno/constants.tex
>  create mode 100644 newlib/libc/machine/cris/constants-errno.tex
>  create mode 100644 newlib/libc/machine/spu/constants-errno.tex

I like the idea in general.  What I'm a bit put off by are the
machine-specific lists.  Ideally they should only contain those values
which differ from the values defined upstream, that is, the values in
newlib/libc/include/sys/errno.h.  But I'd understand if that's too
complicated.


Corinna