[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.
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).