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

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

[Mike Frysinger]

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

diff --git a/newlib/libc/errno/Makefile.inc b/newlib/libc/errno/Makefile.inc
index f06b8c5e8b7b..243091e90a76 100644
--- a/newlib/libc/errno/Makefile.inc
+++ b/newlib/libc/errno/Makefile.inc
@@ -1 +1,4 @@
 libc_a_SOURCES += %D%/errno.c
+
+## NB: Not using LIBC_CHAPTERS because libc.texi includes this directly.
+libc_libc_TEXINFOS += %D%/constants.tex
diff --git a/newlib/libc/errno/constants.tex b/newlib/libc/errno/constants.tex
new file mode 100644
index 000000000000..9b0f85f518c0
--- /dev/null
+++ b/newlib/libc/errno/constants.tex
@@ -0,0 +1,349 @@
+@c This file is machine generated by gennltvals.py.
+
+@subsection Sorted by name
+@multitable @columnfractions .2 .2
+@item @code{E2BIG}
+@tab @code{7}
+@item @code{EACCES}
+@tab @code{13}
+@item @code{EADDRINUSE}
+@tab @code{112}
+@item @code{EADDRNOTAVAIL}
+@tab @code{125}
+@item @code{EAFNOSUPPORT}
+@tab @code{106}
+@item @code{EAGAIN}
+@tab @code{11}
+@item @code{EALREADY}
+@tab @code{120}
+@item @code{EBADF}
+@tab @code{9}
+@item @code{EBADMSG}
+@tab @code{77}
+@item @code{EBUSY}
+@tab @code{16}
+@item @code{ECANCELED}
+@tab @code{140}
+@item @code{ECHILD}
+@tab @code{10}
+@item @code{ECONNABORTED}
+@tab @code{113}
+@item @code{ECONNREFUSED}
+@tab @code{111}
+@item @code{ECONNRESET}
+@tab @code{104}
+@item @code{EDEADLK}
+@tab @code{45}
+@item @code{EDESTADDRREQ}
+@tab @code{121}
+@item @code{EDOM}
+@tab @code{33}
+@item @code{EDQUOT}
+@tab @code{132}
+@item @code{EEXIST}
+@tab @code{17}
+@item @code{EFAULT}
+@tab @code{14}
+@item @code{EFBIG}
+@tab @code{27}
+@item @code{EFTYPE}
+@tab @code{79}
+@item @code{EHOSTDOWN}
+@tab @code{117}
+@item @code{EHOSTUNREACH}
+@tab @code{118}
+@item @code{EIDRM}
+@tab @code{36}
+@item @code{EILSEQ}
+@tab @code{138}
+@item @code{EINPROGRESS}
+@tab @code{119}
+@item @code{EINTR}
+@tab @code{4}
+@item @code{EINVAL}
+@tab @code{22}
+@item @code{EIO}
+@tab @code{5}
+@item @code{EISCONN}
+@tab @code{127}
+@item @code{EISDIR}
+@tab @code{21}
+@item @code{ELOOP}
+@tab @code{92}
+@item @code{EMFILE}
+@tab @code{24}
+@item @code{EMLINK}
+@tab @code{31}
+@item @code{EMSGSIZE}
+@tab @code{122}
+@item @code{EMULTIHOP}
+@tab @code{74}
+@item @code{ENAMETOOLONG}
+@tab @code{91}
+@item @code{ENETDOWN}
+@tab @code{115}
+@item @code{ENETRESET}
+@tab @code{126}
+@item @code{ENETUNREACH}
+@tab @code{114}
+@item @code{ENFILE}
+@tab @code{23}
+@item @code{ENOBUFS}
+@tab @code{105}
+@item @code{ENODATA}
+@tab @code{61}
+@item @code{ENODEV}
+@tab @code{19}
+@item @code{ENOENT}
+@tab @code{2}
+@item @code{ENOEXEC}
+@tab @code{8}
+@item @code{ENOLCK}
+@tab @code{46}
+@item @code{ENOLINK}
+@tab @code{67}
+@item @code{ENOMEM}
+@tab @code{12}
+@item @code{ENOMSG}
+@tab @code{35}
+@item @code{ENOPROTOOPT}
+@tab @code{109}
+@item @code{ENOSPC}
+@tab @code{28}
+@item @code{ENOSR}
+@tab @code{63}
+@item @code{ENOSTR}
+@tab @code{60}
+@item @code{ENOSYS}
+@tab @code{88}
+@item @code{ENOTCONN}
+@tab @code{128}
+@item @code{ENOTDIR}
+@tab @code{20}
+@item @code{ENOTEMPTY}
+@tab @code{90}
+@item @code{ENOTRECOVERABLE}
+@tab @code{141}
+@item @code{ENOTSOCK}
+@tab @code{108}
+@item @code{ENOTSUP}
+@tab @code{134}
+@item @code{ENOTTY}
+@tab @code{25}
+@item @code{ENXIO}
+@tab @code{6}
+@item @code{EOPNOTSUPP}
+@tab @code{95}
+@item @code{EOVERFLOW}
+@tab @code{139}
+@item @code{EOWNERDEAD}
+@tab @code{142}
+@item @code{EPERM}
+@tab @code{1}
+@item @code{EPFNOSUPPORT}
+@tab @code{96}
+@item @code{EPIPE}
+@tab @code{32}
+@item @code{EPROTO}
+@tab @code{71}
+@item @code{EPROTONOSUPPORT}
+@tab @code{123}
+@item @code{EPROTOTYPE}
+@tab @code{107}
+@item @code{ERANGE}
+@tab @code{34}
+@item @code{EROFS}
+@tab @code{30}
+@item @code{ESPIPE}
+@tab @code{29}
+@item @code{ESRCH}
+@tab @code{3}
+@item @code{ESTALE}
+@tab @code{133}
+@item @code{ETIME}
+@tab @code{62}
+@item @code{ETIMEDOUT}
+@tab @code{116}
+@item @code{ETOOMANYREFS}
+@tab @code{129}
+@item @code{ETXTBSY}
+@tab @code{26}
+@item @code{EWOULDBLOCK}
+@tab @code{11}
+@item @code{EXDEV}
+@tab @code{18}
+@end multitable
+
+@subsection Sorted by value
+@multitable @columnfractions .2 .2
+@item @code{EPERM}
+@tab @code{1}
+@item @code{ENOENT}
+@tab @code{2}
+@item @code{ESRCH}
+@tab @code{3}
+@item @code{EINTR}
+@tab @code{4}
+@item @code{EIO}
+@tab @code{5}
+@item @code{ENXIO}
+@tab @code{6}
+@item @code{E2BIG}
+@tab @code{7}
+@item @code{ENOEXEC}
+@tab @code{8}
+@item @code{EBADF}
+@tab @code{9}
+@item @code{ECHILD}
+@tab @code{10}
+@item @code{EAGAIN}
+@tab @code{11}
+@item @code{EWOULDBLOCK}
+@tab @code{11}
+@item @code{ENOMEM}
+@tab @code{12}
+@item @code{EACCES}
+@tab @code{13}
+@item @code{EFAULT}
+@tab @code{14}
+@item @code{EBUSY}
+@tab @code{16}
+@item @code{EEXIST}
+@tab @code{17}
+@item @code{EXDEV}
+@tab @code{18}
+@item @code{ENODEV}
+@tab @code{19}
+@item @code{ENOTDIR}
+@tab @code{20}
+@item @code{EISDIR}
+@tab @code{21}
+@item @code{EINVAL}
+@tab @code{22}
+@item @code{ENFILE}
+@tab @code{23}
+@item @code{EMFILE}
+@tab @code{24}
+@item @code{ENOTTY}
+@tab @code{25}
+@item @code{ETXTBSY}
+@tab @code{26}
+@item @code{EFBIG}
+@tab @code{27}
+@item @code{ENOSPC}
+@tab @code{28}
+@item @code{ESPIPE}
+@tab @code{29}
+@item @code{EROFS}
+@tab @code{30}
+@item @code{EMLINK}
+@tab @code{31}
+@item @code{EPIPE}
+@tab @code{32}
+@item @code{EDOM}
+@tab @code{33}
+@item @code{ERANGE}
+@tab @code{34}
+@item @code{ENOMSG}
+@tab @code{35}
+@item @code{EIDRM}
+@tab @code{36}
+@item @code{EDEADLK}
+@tab @code{45}
+@item @code{ENOLCK}
+@tab @code{46}
+@item @code{ENOSTR}
+@tab @code{60}
+@item @code{ENODATA}
+@tab @code{61}
+@item @code{ETIME}
+@tab @code{62}
+@item @code{ENOSR}
+@tab @code{63}
+@item @code{ENOLINK}
+@tab @code{67}
+@item @code{EPROTO}
+@tab @code{71}
+@item @code{EMULTIHOP}
+@tab @code{74}
+@item @code{EBADMSG}
+@tab @code{77}
+@item @code{EFTYPE}
+@tab @code{79}
+@item @code{ENOSYS}
+@tab @code{88}
+@item @code{ENOTEMPTY}
+@tab @code{90}
+@item @code{ENAMETOOLONG}
+@tab @code{91}
+@item @code{ELOOP}
+@tab @code{92}
+@item @code{EOPNOTSUPP}
+@tab @code{95}
+@item @code{EPFNOSUPPORT}
+@tab @code{96}
+@item @code{ECONNRESET}
+@tab @code{104}
+@item @code{ENOBUFS}
+@tab @code{105}
+@item @code{EAFNOSUPPORT}
+@tab @code{106}
+@item @code{EPROTOTYPE}
+@tab @code{107}
+@item @code{ENOTSOCK}
+@tab @code{108}
+@item @code{ENOPROTOOPT}
+@tab @code{109}
+@item @code{ECONNREFUSED}
+@tab @code{111}
+@item @code{EADDRINUSE}
+@tab @code{112}
+@item @code{ECONNABORTED}
+@tab @code{113}
+@item @code{ENETUNREACH}
+@tab @code{114}
+@item @code{ENETDOWN}
+@tab @code{115}
+@item @code{ETIMEDOUT}
+@tab @code{116}
+@item @code{EHOSTDOWN}
+@tab @code{117}
+@item @code{EHOSTUNREACH}
+@tab @code{118}
+@item @code{EINPROGRESS}
+@tab @code{119}
+@item @code{EALREADY}
+@tab @code{120}
+@item @code{EDESTADDRREQ}
+@tab @code{121}
+@item @code{EMSGSIZE}
+@tab @code{122}
+@item @code{EPROTONOSUPPORT}
+@tab @code{123}
+@item @code{EADDRNOTAVAIL}
+@tab @code{125}
+@item @code{ENETRESET}
+@tab @code{126}
+@item @code{EISCONN}
+@tab @code{127}
+@item @code{ENOTCONN}
+@tab @code{128}
+@item @code{ETOOMANYREFS}
+@tab @code{129}
+@item @code{EDQUOT}
+@tab @code{132}
+@item @code{ESTALE}
+@tab @code{133}
+@item @code{ENOTSUP}
+@tab @code{134}
+@item @code{EILSEQ}
+@tab @code{138}
+@item @code{EOVERFLOW}
+@tab @code{139}
+@item @code{ECANCELED}
+@tab @code{140}
+@item @code{ENOTRECOVERABLE}
+@tab @code{141}
+@item @code{EOWNERDEAD}
+@tab @code{142}
+@end multitable
diff --git a/newlib/libc/libc.texi b/newlib/libc/libc.texi
index a5f24b15a289..8b8604781c77 100644
--- a/newlib/libc/libc.texi
+++ b/newlib/libc/libc.texi
@@ -406,6 +406,32 @@ argument list @var{ap} any further.
 The @code{va_end} defined in @file{varargs.h} has the same syntax and
 usage as the ANSI C version from @file{stdarg.h}.
 
+@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).
+
+@node Newlib ABI Errno
+@section Errno Values
+Most architectures use the common set of errno values.  Only a minor few deviate
+from them.
+
+@subsection Common Errno Values
+@lowersections
+@include errno/constants.tex
+@raisesections
+
+@subsection CRIS Errno Values
+@lowersections
+@include machine/cris/constants-errno.tex
+@raisesections
+
+@subsection SPU Errno Values
+@lowersections
+@include machine/spu/constants-errno.tex
+@raisesections
+
 @node Document Index
 @unnumbered Document Index
 @printindex cp
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
+
+## NB: Not using LIBC_CHAPTERS because libc.texi includes this directly.
+libc_libc_TEXINFOS += %D%/constants-errno.tex
diff --git a/newlib/libc/machine/cris/constants-errno.tex b/newlib/libc/machine/cris/constants-errno.tex
new file mode 100644
index 000000000000..85a76595e971
--- /dev/null
+++ b/newlib/libc/machine/cris/constants-errno.tex
@@ -0,0 +1,541 @@
+@c This file is machine generated by gennltvals.py.
+
+@subsection Sorted by name
+@multitable @columnfractions .2 .2
+@item @code{E2BIG}
+@tab @code{7}
+@item @code{EACCES}
+@tab @code{13}
+@item @code{EADDRINUSE}
+@tab @code{98}
+@item @code{EADDRNOTAVAIL}
+@tab @code{99}
+@item @code{EADV}
+@tab @code{68}
+@item @code{EAFNOSUPPORT}
+@tab @code{97}
+@item @code{EAGAIN}
+@tab @code{11}
+@item @code{EALREADY}
+@tab @code{114}
+@item @code{EBADE}
+@tab @code{52}
+@item @code{EBADF}
+@tab @code{9}
+@item @code{EBADFD}
+@tab @code{77}
+@item @code{EBADMSG}
+@tab @code{74}
+@item @code{EBADR}
+@tab @code{53}
+@item @code{EBADRQC}
+@tab @code{56}
+@item @code{EBADSLT}
+@tab @code{57}
+@item @code{EBFONT}
+@tab @code{59}
+@item @code{EBUSY}
+@tab @code{16}
+@item @code{ECANCELED}
+@tab @code{125}
+@item @code{ECHILD}
+@tab @code{10}
+@item @code{ECHRNG}
+@tab @code{44}
+@item @code{ECOMM}
+@tab @code{70}
+@item @code{ECONNABORTED}
+@tab @code{103}
+@item @code{ECONNREFUSED}
+@tab @code{111}
+@item @code{ECONNRESET}
+@tab @code{104}
+@item @code{EDEADLK}
+@tab @code{35}
+@item @code{EDEADLOCK}
+@tab @code{35}
+@item @code{EDESTADDRREQ}
+@tab @code{89}
+@item @code{EDOM}
+@tab @code{33}
+@item @code{EDOTDOT}
+@tab @code{73}
+@item @code{EDQUOT}
+@tab @code{122}
+@item @code{EEXIST}
+@tab @code{17}
+@item @code{EFAULT}
+@tab @code{14}
+@item @code{EFBIG}
+@tab @code{27}
+@item @code{EFTYPE}
+@tab @code{59}
+@item @code{EHOSTDOWN}
+@tab @code{112}
+@item @code{EHOSTUNREACH}
+@tab @code{113}
+@item @code{EIDRM}
+@tab @code{43}
+@item @code{EILSEQ}
+@tab @code{84}
+@item @code{EINPROGRESS}
+@tab @code{115}
+@item @code{EINTR}
+@tab @code{4}
+@item @code{EINVAL}
+@tab @code{22}
+@item @code{EIO}
+@tab @code{5}
+@item @code{EISCONN}
+@tab @code{106}
+@item @code{EISDIR}
+@tab @code{21}
+@item @code{EISNAM}
+@tab @code{120}
+@item @code{EKEYEXPIRED}
+@tab @code{127}
+@item @code{EKEYREJECTED}
+@tab @code{129}
+@item @code{EKEYREVOKED}
+@tab @code{128}
+@item @code{EL2HLT}
+@tab @code{51}
+@item @code{EL2NSYNC}
+@tab @code{45}
+@item @code{EL3HLT}
+@tab @code{46}
+@item @code{EL3RST}
+@tab @code{47}
+@item @code{ELIBACC}
+@tab @code{79}
+@item @code{ELIBBAD}
+@tab @code{80}
+@item @code{ELIBEXEC}
+@tab @code{83}
+@item @code{ELIBMAX}
+@tab @code{82}
+@item @code{ELIBSCN}
+@tab @code{81}
+@item @code{ELNRNG}
+@tab @code{48}
+@item @code{ELOOP}
+@tab @code{40}
+@item @code{EMEDIUMTYPE}
+@tab @code{124}
+@item @code{EMFILE}
+@tab @code{24}
+@item @code{EMLINK}
+@tab @code{31}
+@item @code{EMSGSIZE}
+@tab @code{90}
+@item @code{EMULTIHOP}
+@tab @code{72}
+@item @code{ENAMETOOLONG}
+@tab @code{36}
+@item @code{ENAVAIL}
+@tab @code{119}
+@item @code{ENETDOWN}
+@tab @code{100}
+@item @code{ENETRESET}
+@tab @code{102}
+@item @code{ENETUNREACH}
+@tab @code{101}
+@item @code{ENFILE}
+@tab @code{23}
+@item @code{ENOANO}
+@tab @code{55}
+@item @code{ENOBUFS}
+@tab @code{105}
+@item @code{ENOCSI}
+@tab @code{50}
+@item @code{ENODATA}
+@tab @code{61}
+@item @code{ENODEV}
+@tab @code{19}
+@item @code{ENOENT}
+@tab @code{2}
+@item @code{ENOEXEC}
+@tab @code{8}
+@item @code{ENOKEY}
+@tab @code{126}
+@item @code{ENOLCK}
+@tab @code{37}
+@item @code{ENOLINK}
+@tab @code{67}
+@item @code{ENOMEDIUM}
+@tab @code{123}
+@item @code{ENOMEM}
+@tab @code{12}
+@item @code{ENOMSG}
+@tab @code{42}
+@item @code{ENONET}
+@tab @code{64}
+@item @code{ENOPKG}
+@tab @code{65}
+@item @code{ENOPROTOOPT}
+@tab @code{92}
+@item @code{ENOSPC}
+@tab @code{28}
+@item @code{ENOSR}
+@tab @code{63}
+@item @code{ENOSTR}
+@tab @code{60}
+@item @code{ENOSYS}
+@tab @code{38}
+@item @code{ENOTBLK}
+@tab @code{15}
+@item @code{ENOTCONN}
+@tab @code{107}
+@item @code{ENOTDIR}
+@tab @code{20}
+@item @code{ENOTEMPTY}
+@tab @code{39}
+@item @code{ENOTNAM}
+@tab @code{118}
+@item @code{ENOTRECOVERABLE}
+@tab @code{131}
+@item @code{ENOTSOCK}
+@tab @code{88}
+@item @code{ENOTSUP}
+@tab @code{95}
+@item @code{ENOTTY}
+@tab @code{25}
+@item @code{ENOTUNIQ}
+@tab @code{76}
+@item @code{ENXIO}
+@tab @code{6}
+@item @code{EOPNOTSUPP}
+@tab @code{95}
+@item @code{EOVERFLOW}
+@tab @code{75}
+@item @code{EOWNERDEAD}
+@tab @code{130}
+@item @code{EPERM}
+@tab @code{1}
+@item @code{EPFNOSUPPORT}
+@tab @code{96}
+@item @code{EPIPE}
+@tab @code{32}
+@item @code{EPROTO}
+@tab @code{71}
+@item @code{EPROTONOSUPPORT}
+@tab @code{93}
+@item @code{EPROTOTYPE}
+@tab @code{91}
+@item @code{ERANGE}
+@tab @code{34}
+@item @code{EREMCHG}
+@tab @code{78}
+@item @code{EREMOTE}
+@tab @code{66}
+@item @code{EREMOTEIO}
+@tab @code{121}
+@item @code{ERESTART}
+@tab @code{85}
+@item @code{EROFS}
+@tab @code{30}
+@item @code{ESHUTDOWN}
+@tab @code{108}
+@item @code{ESOCKTNOSUPPORT}
+@tab @code{94}
+@item @code{ESPIPE}
+@tab @code{29}
+@item @code{ESRCH}
+@tab @code{3}
+@item @code{ESRMNT}
+@tab @code{69}
+@item @code{ESTALE}
+@tab @code{116}
+@item @code{ESTRPIPE}
+@tab @code{86}
+@item @code{ETIME}
+@tab @code{62}
+@item @code{ETIMEDOUT}
+@tab @code{110}
+@item @code{ETOOMANYREFS}
+@tab @code{109}
+@item @code{ETXTBSY}
+@tab @code{26}
+@item @code{EUCLEAN}
+@tab @code{117}
+@item @code{EUNATCH}
+@tab @code{49}
+@item @code{EUSERS}
+@tab @code{87}
+@item @code{EWOULDBLOCK}
+@tab @code{11}
+@item @code{EXDEV}
+@tab @code{18}
+@item @code{EXFULL}
+@tab @code{54}
+@end multitable
+
+@subsection Sorted by value
+@multitable @columnfractions .2 .2
+@item @code{EPERM}
+@tab @code{1}
+@item @code{ENOENT}
+@tab @code{2}
+@item @code{ESRCH}
+@tab @code{3}
+@item @code{EINTR}
+@tab @code{4}
+@item @code{EIO}
+@tab @code{5}
+@item @code{ENXIO}
+@tab @code{6}
+@item @code{E2BIG}
+@tab @code{7}
+@item @code{ENOEXEC}
+@tab @code{8}
+@item @code{EBADF}
+@tab @code{9}
+@item @code{ECHILD}
+@tab @code{10}
+@item @code{EAGAIN}
+@tab @code{11}
+@item @code{EWOULDBLOCK}
+@tab @code{11}
+@item @code{ENOMEM}
+@tab @code{12}
+@item @code{EACCES}
+@tab @code{13}
+@item @code{EFAULT}
+@tab @code{14}
+@item @code{ENOTBLK}
+@tab @code{15}
+@item @code{EBUSY}
+@tab @code{16}
+@item @code{EEXIST}
+@tab @code{17}
+@item @code{EXDEV}
+@tab @code{18}
+@item @code{ENODEV}
+@tab @code{19}
+@item @code{ENOTDIR}
+@tab @code{20}
+@item @code{EISDIR}
+@tab @code{21}
+@item @code{EINVAL}
+@tab @code{22}
+@item @code{ENFILE}
+@tab @code{23}
+@item @code{EMFILE}
+@tab @code{24}
+@item @code{ENOTTY}
+@tab @code{25}
+@item @code{ETXTBSY}
+@tab @code{26}
+@item @code{EFBIG}
+@tab @code{27}
+@item @code{ENOSPC}
+@tab @code{28}
+@item @code{ESPIPE}
+@tab @code{29}
+@item @code{EROFS}
+@tab @code{30}
+@item @code{EMLINK}
+@tab @code{31}
+@item @code{EPIPE}
+@tab @code{32}
+@item @code{EDOM}
+@tab @code{33}
+@item @code{ERANGE}
+@tab @code{34}
+@item @code{EDEADLK}
+@tab @code{35}
+@item @code{EDEADLOCK}
+@tab @code{35}
+@item @code{ENAMETOOLONG}
+@tab @code{36}
+@item @code{ENOLCK}
+@tab @code{37}
+@item @code{ENOSYS}
+@tab @code{38}
+@item @code{ENOTEMPTY}
+@tab @code{39}
+@item @code{ELOOP}
+@tab @code{40}
+@item @code{ENOMSG}
+@tab @code{42}
+@item @code{EIDRM}
+@tab @code{43}
+@item @code{ECHRNG}
+@tab @code{44}
+@item @code{EL2NSYNC}
+@tab @code{45}
+@item @code{EL3HLT}
+@tab @code{46}
+@item @code{EL3RST}
+@tab @code{47}
+@item @code{ELNRNG}
+@tab @code{48}
+@item @code{EUNATCH}
+@tab @code{49}
+@item @code{ENOCSI}
+@tab @code{50}
+@item @code{EL2HLT}
+@tab @code{51}
+@item @code{EBADE}
+@tab @code{52}
+@item @code{EBADR}
+@tab @code{53}
+@item @code{EXFULL}
+@tab @code{54}
+@item @code{ENOANO}
+@tab @code{55}
+@item @code{EBADRQC}
+@tab @code{56}
+@item @code{EBADSLT}
+@tab @code{57}
+@item @code{EBFONT}
+@tab @code{59}
+@item @code{EFTYPE}
+@tab @code{59}
+@item @code{ENOSTR}
+@tab @code{60}
+@item @code{ENODATA}
+@tab @code{61}
+@item @code{ETIME}
+@tab @code{62}
+@item @code{ENOSR}
+@tab @code{63}
+@item @code{ENONET}
+@tab @code{64}
+@item @code{ENOPKG}
+@tab @code{65}
+@item @code{EREMOTE}
+@tab @code{66}
+@item @code{ENOLINK}
+@tab @code{67}
+@item @code{EADV}
+@tab @code{68}
+@item @code{ESRMNT}
+@tab @code{69}
+@item @code{ECOMM}
+@tab @code{70}
+@item @code{EPROTO}
+@tab @code{71}
+@item @code{EMULTIHOP}
+@tab @code{72}
+@item @code{EDOTDOT}
+@tab @code{73}
+@item @code{EBADMSG}
+@tab @code{74}
+@item @code{EOVERFLOW}
+@tab @code{75}
+@item @code{ENOTUNIQ}
+@tab @code{76}
+@item @code{EBADFD}
+@tab @code{77}
+@item @code{EREMCHG}
+@tab @code{78}
+@item @code{ELIBACC}
+@tab @code{79}
+@item @code{ELIBBAD}
+@tab @code{80}
+@item @code{ELIBSCN}
+@tab @code{81}
+@item @code{ELIBMAX}
+@tab @code{82}
+@item @code{ELIBEXEC}
+@tab @code{83}
+@item @code{EILSEQ}
+@tab @code{84}
+@item @code{ERESTART}
+@tab @code{85}
+@item @code{ESTRPIPE}
+@tab @code{86}
+@item @code{EUSERS}
+@tab @code{87}
+@item @code{ENOTSOCK}
+@tab @code{88}
+@item @code{EDESTADDRREQ}
+@tab @code{89}
+@item @code{EMSGSIZE}
+@tab @code{90}
+@item @code{EPROTOTYPE}
+@tab @code{91}
+@item @code{ENOPROTOOPT}
+@tab @code{92}
+@item @code{EPROTONOSUPPORT}
+@tab @code{93}
+@item @code{ESOCKTNOSUPPORT}
+@tab @code{94}
+@item @code{ENOTSUP}
+@tab @code{95}
+@item @code{EOPNOTSUPP}
+@tab @code{95}
+@item @code{EPFNOSUPPORT}
+@tab @code{96}
+@item @code{EAFNOSUPPORT}
+@tab @code{97}
+@item @code{EADDRINUSE}
+@tab @code{98}
+@item @code{EADDRNOTAVAIL}
+@tab @code{99}
+@item @code{ENETDOWN}
+@tab @code{100}
+@item @code{ENETUNREACH}
+@tab @code{101}
+@item @code{ENETRESET}
+@tab @code{102}
+@item @code{ECONNABORTED}
+@tab @code{103}
+@item @code{ECONNRESET}
+@tab @code{104}
+@item @code{ENOBUFS}
+@tab @code{105}
+@item @code{EISCONN}
+@tab @code{106}
+@item @code{ENOTCONN}
+@tab @code{107}
+@item @code{ESHUTDOWN}
+@tab @code{108}
+@item @code{ETOOMANYREFS}
+@tab @code{109}
+@item @code{ETIMEDOUT}
+@tab @code{110}
+@item @code{ECONNREFUSED}
+@tab @code{111}
+@item @code{EHOSTDOWN}
+@tab @code{112}
+@item @code{EHOSTUNREACH}
+@tab @code{113}
+@item @code{EALREADY}
+@tab @code{114}
+@item @code{EINPROGRESS}
+@tab @code{115}
+@item @code{ESTALE}
+@tab @code{116}
+@item @code{EUCLEAN}
+@tab @code{117}
+@item @code{ENOTNAM}
+@tab @code{118}
+@item @code{ENAVAIL}
+@tab @code{119}
+@item @code{EISNAM}
+@tab @code{120}
+@item @code{EREMOTEIO}
+@tab @code{121}
+@item @code{EDQUOT}
+@tab @code{122}
+@item @code{ENOMEDIUM}
+@tab @code{123}
+@item @code{EMEDIUMTYPE}
+@tab @code{124}
+@item @code{ECANCELED}
+@tab @code{125}
+@item @code{ENOKEY}
+@tab @code{126}
+@item @code{EKEYEXPIRED}
+@tab @code{127}
+@item @code{EKEYREVOKED}
+@tab @code{128}
+@item @code{EKEYREJECTED}
+@tab @code{129}
+@item @code{EOWNERDEAD}
+@tab @code{130}
+@item @code{ENOTRECOVERABLE}
+@tab @code{131}
+@end multitable
diff --git a/newlib/libc/machine/spu/Makefile.inc b/newlib/libc/machine/spu/Makefile.inc
index 5384a5f28560..be265a4143e8 100644
--- a/newlib/libc/machine/spu/Makefile.inc
+++ b/newlib/libc/machine/spu/Makefile.inc
@@ -26,3 +26,6 @@ libc_a_SOURCES += \
 	%D%/pread_ea.c %D%/readv_ea.c %D%/write_ea.c %D%/pwrite_ea.c %D%/writev_ea.c %D%/spu-mcount.S \
 	%D%/spu-gmon.c
 endif
+
+## NB: Not using LIBC_CHAPTERS because libc.texi includes this directly.
+libc_libc_TEXINFOS += %D%/constants-errno.tex
diff --git a/newlib/libc/machine/spu/constants-errno.tex b/newlib/libc/machine/spu/constants-errno.tex
new file mode 100644
index 000000000000..0d71176cfeca
--- /dev/null
+++ b/newlib/libc/machine/spu/constants-errno.tex
@@ -0,0 +1,517 @@
+@c This file is machine generated by gennltvals.py.
+
+@subsection Sorted by name
+@multitable @columnfractions .2 .2
+@item @code{E2BIG}
+@tab @code{7}
+@item @code{EACCES}
+@tab @code{13}
+@item @code{EADDRINUSE}
+@tab @code{98}
+@item @code{EADDRNOTAVAIL}
+@tab @code{99}
+@item @code{EADV}
+@tab @code{68}
+@item @code{EAFNOSUPPORT}
+@tab @code{97}
+@item @code{EAGAIN}
+@tab @code{11}
+@item @code{EALREADY}
+@tab @code{114}
+@item @code{EBADE}
+@tab @code{52}
+@item @code{EBADF}
+@tab @code{9}
+@item @code{EBADFD}
+@tab @code{77}
+@item @code{EBADMSG}
+@tab @code{74}
+@item @code{EBADR}
+@tab @code{53}
+@item @code{EBADRQC}
+@tab @code{56}
+@item @code{EBADSLT}
+@tab @code{57}
+@item @code{EBFONT}
+@tab @code{59}
+@item @code{EBUSY}
+@tab @code{16}
+@item @code{ECANCELED}
+@tab @code{125}
+@item @code{ECHILD}
+@tab @code{10}
+@item @code{ECHRNG}
+@tab @code{44}
+@item @code{ECOMM}
+@tab @code{70}
+@item @code{ECONNABORTED}
+@tab @code{103}
+@item @code{ECONNREFUSED}
+@tab @code{111}
+@item @code{ECONNRESET}
+@tab @code{104}
+@item @code{EDEADLK}
+@tab @code{35}
+@item @code{EDEADLOCK}
+@tab @code{58}
+@item @code{EDESTADDRREQ}
+@tab @code{89}
+@item @code{EDOM}
+@tab @code{33}
+@item @code{EDOTDOT}
+@tab @code{73}
+@item @code{EDQUOT}
+@tab @code{122}
+@item @code{EEXIST}
+@tab @code{17}
+@item @code{EFAULT}
+@tab @code{14}
+@item @code{EFBIG}
+@tab @code{27}
+@item @code{EFTYPE}
+@tab @code{59}
+@item @code{EHOSTDOWN}
+@tab @code{112}
+@item @code{EHOSTUNREACH}
+@tab @code{113}
+@item @code{EIDRM}
+@tab @code{43}
+@item @code{EILSEQ}
+@tab @code{84}
+@item @code{EINPROGRESS}
+@tab @code{115}
+@item @code{EINTR}
+@tab @code{4}
+@item @code{EINVAL}
+@tab @code{22}
+@item @code{EIO}
+@tab @code{5}
+@item @code{EISCONN}
+@tab @code{106}
+@item @code{EISDIR}
+@tab @code{21}
+@item @code{EISNAM}
+@tab @code{120}
+@item @code{EL2HLT}
+@tab @code{51}
+@item @code{EL2NSYNC}
+@tab @code{45}
+@item @code{EL3HLT}
+@tab @code{46}
+@item @code{EL3RST}
+@tab @code{47}
+@item @code{ELIBACC}
+@tab @code{79}
+@item @code{ELIBBAD}
+@tab @code{80}
+@item @code{ELIBEXEC}
+@tab @code{83}
+@item @code{ELIBMAX}
+@tab @code{82}
+@item @code{ELIBSCN}
+@tab @code{81}
+@item @code{ELNRNG}
+@tab @code{48}
+@item @code{ELOOP}
+@tab @code{40}
+@item @code{EMEDIUMTYPE}
+@tab @code{124}
+@item @code{EMFILE}
+@tab @code{24}
+@item @code{EMLINK}
+@tab @code{31}
+@item @code{EMSGSIZE}
+@tab @code{90}
+@item @code{EMULTIHOP}
+@tab @code{72}
+@item @code{ENAMETOOLONG}
+@tab @code{36}
+@item @code{ENAVAIL}
+@tab @code{119}
+@item @code{ENETDOWN}
+@tab @code{100}
+@item @code{ENETRESET}
+@tab @code{102}
+@item @code{ENETUNREACH}
+@tab @code{101}
+@item @code{ENFILE}
+@tab @code{23}
+@item @code{ENOANO}
+@tab @code{55}
+@item @code{ENOBUFS}
+@tab @code{105}
+@item @code{ENOCSI}
+@tab @code{50}
+@item @code{ENODATA}
+@tab @code{61}
+@item @code{ENODEV}
+@tab @code{19}
+@item @code{ENOENT}
+@tab @code{2}
+@item @code{ENOEXEC}
+@tab @code{8}
+@item @code{ENOLCK}
+@tab @code{37}
+@item @code{ENOLINK}
+@tab @code{67}
+@item @code{ENOMEDIUM}
+@tab @code{123}
+@item @code{ENOMEM}
+@tab @code{12}
+@item @code{ENOMSG}
+@tab @code{42}
+@item @code{ENONET}
+@tab @code{64}
+@item @code{ENOPKG}
+@tab @code{65}
+@item @code{ENOPROTOOPT}
+@tab @code{92}
+@item @code{ENOSPC}
+@tab @code{28}
+@item @code{ENOSR}
+@tab @code{63}
+@item @code{ENOSTR}
+@tab @code{60}
+@item @code{ENOSYS}
+@tab @code{38}
+@item @code{ENOTBLK}
+@tab @code{15}
+@item @code{ENOTCONN}
+@tab @code{107}
+@item @code{ENOTDIR}
+@tab @code{20}
+@item @code{ENOTEMPTY}
+@tab @code{39}
+@item @code{ENOTNAM}
+@tab @code{118}
+@item @code{ENOTSOCK}
+@tab @code{88}
+@item @code{ENOTSUP}
+@tab @code{95}
+@item @code{ENOTTY}
+@tab @code{25}
+@item @code{ENOTUNIQ}
+@tab @code{76}
+@item @code{ENXIO}
+@tab @code{6}
+@item @code{EOPNOTSUPP}
+@tab @code{95}
+@item @code{EOVERFLOW}
+@tab @code{75}
+@item @code{EPERM}
+@tab @code{1}
+@item @code{EPFNOSUPPORT}
+@tab @code{96}
+@item @code{EPIPE}
+@tab @code{32}
+@item @code{EPROTO}
+@tab @code{71}
+@item @code{EPROTONOSUPPORT}
+@tab @code{93}
+@item @code{EPROTOTYPE}
+@tab @code{91}
+@item @code{ERANGE}
+@tab @code{34}
+@item @code{EREMCHG}
+@tab @code{78}
+@item @code{EREMOTE}
+@tab @code{66}
+@item @code{EREMOTEIO}
+@tab @code{121}
+@item @code{ERESTART}
+@tab @code{85}
+@item @code{EROFS}
+@tab @code{30}
+@item @code{ESHUTDOWN}
+@tab @code{108}
+@item @code{ESOCKTNOSUPPORT}
+@tab @code{94}
+@item @code{ESPIPE}
+@tab @code{29}
+@item @code{ESRCH}
+@tab @code{3}
+@item @code{ESRMNT}
+@tab @code{69}
+@item @code{ESTALE}
+@tab @code{116}
+@item @code{ESTRPIPE}
+@tab @code{86}
+@item @code{ETIME}
+@tab @code{62}
+@item @code{ETIMEDOUT}
+@tab @code{110}
+@item @code{ETOOMANYREFS}
+@tab @code{109}
+@item @code{ETXTBSY}
+@tab @code{26}
+@item @code{EUCLEAN}
+@tab @code{117}
+@item @code{EUNATCH}
+@tab @code{49}
+@item @code{EUSERS}
+@tab @code{87}
+@item @code{EWOULDBLOCK}
+@tab @code{11}
+@item @code{EXDEV}
+@tab @code{18}
+@item @code{EXFULL}
+@tab @code{54}
+@end multitable
+
+@subsection Sorted by value
+@multitable @columnfractions .2 .2
+@item @code{EPERM}
+@tab @code{1}
+@item @code{ENOENT}
+@tab @code{2}
+@item @code{ESRCH}
+@tab @code{3}
+@item @code{EINTR}
+@tab @code{4}
+@item @code{EIO}
+@tab @code{5}
+@item @code{ENXIO}
+@tab @code{6}
+@item @code{E2BIG}
+@tab @code{7}
+@item @code{ENOEXEC}
+@tab @code{8}
+@item @code{EBADF}
+@tab @code{9}
+@item @code{ECHILD}
+@tab @code{10}
+@item @code{EAGAIN}
+@tab @code{11}
+@item @code{EWOULDBLOCK}
+@tab @code{11}
+@item @code{ENOMEM}
+@tab @code{12}
+@item @code{EACCES}
+@tab @code{13}
+@item @code{EFAULT}
+@tab @code{14}
+@item @code{ENOTBLK}
+@tab @code{15}
+@item @code{EBUSY}
+@tab @code{16}
+@item @code{EEXIST}
+@tab @code{17}
+@item @code{EXDEV}
+@tab @code{18}
+@item @code{ENODEV}
+@tab @code{19}
+@item @code{ENOTDIR}
+@tab @code{20}
+@item @code{EISDIR}
+@tab @code{21}
+@item @code{EINVAL}
+@tab @code{22}
+@item @code{ENFILE}
+@tab @code{23}
+@item @code{EMFILE}
+@tab @code{24}
+@item @code{ENOTTY}
+@tab @code{25}
+@item @code{ETXTBSY}
+@tab @code{26}
+@item @code{EFBIG}
+@tab @code{27}
+@item @code{ENOSPC}
+@tab @code{28}
+@item @code{ESPIPE}
+@tab @code{29}
+@item @code{EROFS}
+@tab @code{30}
+@item @code{EMLINK}
+@tab @code{31}
+@item @code{EPIPE}
+@tab @code{32}
+@item @code{EDOM}
+@tab @code{33}
+@item @code{ERANGE}
+@tab @code{34}
+@item @code{EDEADLK}
+@tab @code{35}
+@item @code{ENAMETOOLONG}
+@tab @code{36}
+@item @code{ENOLCK}
+@tab @code{37}
+@item @code{ENOSYS}
+@tab @code{38}
+@item @code{ENOTEMPTY}
+@tab @code{39}
+@item @code{ELOOP}
+@tab @code{40}
+@item @code{ENOMSG}
+@tab @code{42}
+@item @code{EIDRM}
+@tab @code{43}
+@item @code{ECHRNG}
+@tab @code{44}
+@item @code{EL2NSYNC}
+@tab @code{45}
+@item @code{EL3HLT}
+@tab @code{46}
+@item @code{EL3RST}
+@tab @code{47}
+@item @code{ELNRNG}
+@tab @code{48}
+@item @code{EUNATCH}
+@tab @code{49}
+@item @code{ENOCSI}
+@tab @code{50}
+@item @code{EL2HLT}
+@tab @code{51}
+@item @code{EBADE}
+@tab @code{52}
+@item @code{EBADR}
+@tab @code{53}
+@item @code{EXFULL}
+@tab @code{54}
+@item @code{ENOANO}
+@tab @code{55}
+@item @code{EBADRQC}
+@tab @code{56}
+@item @code{EBADSLT}
+@tab @code{57}
+@item @code{EDEADLOCK}
+@tab @code{58}
+@item @code{EBFONT}
+@tab @code{59}
+@item @code{EFTYPE}
+@tab @code{59}
+@item @code{ENOSTR}
+@tab @code{60}
+@item @code{ENODATA}
+@tab @code{61}
+@item @code{ETIME}
+@tab @code{62}
+@item @code{ENOSR}
+@tab @code{63}
+@item @code{ENONET}
+@tab @code{64}
+@item @code{ENOPKG}
+@tab @code{65}
+@item @code{EREMOTE}
+@tab @code{66}
+@item @code{ENOLINK}
+@tab @code{67}
+@item @code{EADV}
+@tab @code{68}
+@item @code{ESRMNT}
+@tab @code{69}
+@item @code{ECOMM}
+@tab @code{70}
+@item @code{EPROTO}
+@tab @code{71}
+@item @code{EMULTIHOP}
+@tab @code{72}
+@item @code{EDOTDOT}
+@tab @code{73}
+@item @code{EBADMSG}
+@tab @code{74}
+@item @code{EOVERFLOW}
+@tab @code{75}
+@item @code{ENOTUNIQ}
+@tab @code{76}
+@item @code{EBADFD}
+@tab @code{77}
+@item @code{EREMCHG}
+@tab @code{78}
+@item @code{ELIBACC}
+@tab @code{79}
+@item @code{ELIBBAD}
+@tab @code{80}
+@item @code{ELIBSCN}
+@tab @code{81}
+@item @code{ELIBMAX}
+@tab @code{82}
+@item @code{ELIBEXEC}
+@tab @code{83}
+@item @code{EILSEQ}
+@tab @code{84}
+@item @code{ERESTART}
+@tab @code{85}
+@item @code{ESTRPIPE}
+@tab @code{86}
+@item @code{EUSERS}
+@tab @code{87}
+@item @code{ENOTSOCK}
+@tab @code{88}
+@item @code{EDESTADDRREQ}
+@tab @code{89}
+@item @code{EMSGSIZE}
+@tab @code{90}
+@item @code{EPROTOTYPE}
+@tab @code{91}
+@item @code{ENOPROTOOPT}
+@tab @code{92}
+@item @code{EPROTONOSUPPORT}
+@tab @code{93}
+@item @code{ESOCKTNOSUPPORT}
+@tab @code{94}
+@item @code{ENOTSUP}
+@tab @code{95}
+@item @code{EOPNOTSUPP}
+@tab @code{95}
+@item @code{EPFNOSUPPORT}
+@tab @code{96}
+@item @code{EAFNOSUPPORT}
+@tab @code{97}
+@item @code{EADDRINUSE}
+@tab @code{98}
+@item @code{EADDRNOTAVAIL}
+@tab @code{99}
+@item @code{ENETDOWN}
+@tab @code{100}
+@item @code{ENETUNREACH}
+@tab @code{101}
+@item @code{ENETRESET}
+@tab @code{102}
+@item @code{ECONNABORTED}
+@tab @code{103}
+@item @code{ECONNRESET}
+@tab @code{104}
+@item @code{ENOBUFS}
+@tab @code{105}
+@item @code{EISCONN}
+@tab @code{106}
+@item @code{ENOTCONN}
+@tab @code{107}
+@item @code{ESHUTDOWN}
+@tab @code{108}
+@item @code{ETOOMANYREFS}
+@tab @code{109}
+@item @code{ETIMEDOUT}
+@tab @code{110}
+@item @code{ECONNREFUSED}
+@tab @code{111}
+@item @code{EHOSTDOWN}
+@tab @code{112}
+@item @code{EHOSTUNREACH}
+@tab @code{113}
+@item @code{EALREADY}
+@tab @code{114}
+@item @code{EINPROGRESS}
+@tab @code{115}
+@item @code{ESTALE}
+@tab @code{116}
+@item @code{EUCLEAN}
+@tab @code{117}
+@item @code{ENOTNAM}
+@tab @code{118}
+@item @code{ENAVAIL}
+@tab @code{119}
+@item @code{EISNAM}
+@tab @code{120}
+@item @code{EREMOTEIO}
+@tab @code{121}
+@item @code{EDQUOT}
+@tab @code{122}
+@item @code{ENOMEDIUM}
+@tab @code{123}
+@item @code{EMEDIUMTYPE}
+@tab @code{124}
+@item @code{ECANCELED}
+@tab @code{125}
+@end multitable
-- 
2.43.0

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

[C Howland]

[-- Attachment #1: Type: text/plain, Size: 4692 bytes --]

>
> -----Original Message-----
> From: Mike Frysinger <vapier@gentoo.org>
> 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

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

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 4038 bytes --]

On 29 Dec 2023 20:17, C Howland wrote:
>      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.

if you only use newlib, it could be helpful.  consider how common it is for
people to write error messages like:
	printf("error %i\n", errno);
so your log contains "error 13".  how do you find out what errno 13 is ?
even Linux's `man errno` doesn't list the raw numbers.  having online access
to the name<->number mappings for these is helpful in a pinch in my experience.

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

the GNU sim script can already extract the code and turn it into structured
data (e.g. JSON).  it can also turn that into a C file for the generated table.
i would expect the export-to-JSON to be part of the script for merging into
newlib so that the people who need access to the ABI in source form can easily
get it and convert it to whatever format they need.  so the sim would switch to
running the newlib script to get the JSON, but it would keep the output-to-C
logic since that's sim-specific.

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

the script is written in Python and uses a preprocessor (e.g. gcc) to dump
the constants.  gcc has a -CC option to include line-level comments, so this
is a possibility.  it would require the source be structured in a way where
the comments are inline which it mostly already is.

>      It might be better to enhance the wording here a little.

i half-assed this content to show the general structure.  i'm sure the hand
written descriptions could use improvement.  i'll take your feedback in once
i get a signal from the newlib maintainers on this in general.

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

*shrug* it was easy enough to generate.  i find sorted-by-name helpful when
i want to see if a specific name is available, perhaps under a slight name
variant (when i can't remember exactly how it's been abbreviated), and i find
sorted-by-number helpful when looking up an error number from log output.
if we only have sorted-by-name, searching for a single digit number is a bit
of a pita because it'll match numbers in the constant name, in the comment,
and in the multi-digit errno values.  it's not uncommon for the user agent
to support only case-insensitive substrings (e.g. Chrome), and needing regex
just to construct an exact match seems a bit too much for a general manual.

for example:
$ gcc -E -P -dD -CC - <<<'#include <errno.h>' | grep 2
<35 errno matches>

but it's not something i'm strongly tied to, so if the newlib maintainers
want to use one or the other, i don't care enough to fight.
-mike

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [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

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

[brian.inglis]

On 2023-12-29 22:03, Mike Frysinger wrote:
> On 29 Dec 2023 20:17, C Howland wrote:
>>       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.
> 
> if you only use newlib, it could be helpful.  consider how common it is for
> people to write error messages like:
> 	printf("error %i\n", errno);
> so your log contains "error 13".  how do you find out what errno 13 is ?
> even Linux's `man errno` doesn't list the raw numbers.  having online access
> to the name<->number mappings for these is helpful in a pinch in my experience.

moreutils errno?

	https://joeyh.name/code/moreutils/
	https://repology.org/project/moreutils/versions

- perhaps with creative use of "locales" (or patches) for different library 
sources and board support?

>>       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.
> 
> the GNU sim script can already extract the code and turn it into structured
> data (e.g. JSON).  it can also turn that into a C file for the generated table.
> i would expect the export-to-JSON to be part of the script for merging into
> newlib so that the people who need access to the ABI in source form can easily
> get it and convert it to whatever format they need.  so the sim would switch to
> running the newlib script to get the JSON, but it would keep the output-to-C
> logic since that's sim-specific.
> 
>>       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.)
> 
> the script is written in Python and uses a preprocessor (e.g. gcc) to dump
> the constants.  gcc has a -CC option to include line-level comments, so this
> is a possibility.  it would require the source be structured in a way where
> the comments are inline which it mostly already is.
> 
>>       It might be better to enhance the wording here a little.
> 
> i half-assed this content to show the general structure.  i'm sure the hand
> written descriptions could use improvement.  i'll take your feedback in once
> i get a signal from the newlib maintainers on this in general.
> 
>> 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.)
> 
> *shrug* it was easy enough to generate.  i find sorted-by-name helpful when
> i want to see if a specific name is available, perhaps under a slight name
> variant (when i can't remember exactly how it's been abbreviated), and i find
> sorted-by-number helpful when looking up an error number from log output.
> if we only have sorted-by-name, searching for a single digit number is a bit
> of a pita because it'll match numbers in the constant name, in the comment,
> and in the multi-digit errno values.  it's not uncommon for the user agent
> to support only case-insensitive substrings (e.g. Chrome), and needing regex
> just to construct an exact match seems a bit too much for a general manual.
> 
> for example:
> $ gcc -E -P -dD -CC - <<<'#include <errno.h>' | grep 2
> <35 errno matches>
> 
> but it's not something i'm strongly tied to, so if the newlib maintainers
> want to use one or the other, i don't care enough to fight.
> -mike

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

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

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 1468 bytes --]

On 23 Jan 2024 14:05, brian.inglis@systematicsw.ab.ca wrote:
> On 2023-12-29 22:03, Mike Frysinger wrote:
> > On 29 Dec 2023 20:17, C Howland wrote:
> >>       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.
> > 
> > if you only use newlib, it could be helpful.  consider how common it is for
> > people to write error messages like:
> > 	printf("error %i\n", errno);
> > so your log contains "error 13".  how do you find out what errno 13 is ?
> > even Linux's `man errno` doesn't list the raw numbers.  having online access
> > to the name<->number mappings for these is helpful in a pinch in my experience.
> 
> moreutils errno?
> 
> 	https://joeyh.name/code/moreutils/
> 	https://repology.org/project/moreutils/versions
> 
> - perhaps with creative use of "locales" (or patches) for different library 
> sources and board support?

right, it currently only works for the current ABI.  and requires you be
running a *NIX compatible system.  i think it's not uncommon for people to
have Windows as their main desktop in the embedded space.  i know Windows
has been gaining Linux layers, but still seems over the top to look up a
number/constant.

might also be worth seeing if they're interested in expanding as you suggest,
but it's not something i'm going to look into tbh.
-mike

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]