3ed024dcb2
* libc/include/math.h: (llround, llroundf): Declare.
* libm/common/s_llround.c: New file, implementing llround().
* libm/common/sf_llround.c: New file, implementing llroundf().
* libm/common/sf_lround.c: Remove spurious cast in _DOUBLE_IS_32BITS
version of function.
* libm/common/sf_lrint.c: Ditto.
* libm/common/sf_logb.c: Corrected return for subnormal argument
by replacing existing function with a version created from sf_ilogb.c.
* libm/common/s_logb.c: Ditto, except starting point s_ilogb.c. Also
added documentation for logb() and logbf().
* libm/common/s_signbit.c: Add signbit() documentation.
* libm/common/s_log2.c: Update return values to match what w_log2.c has,
since log2 uses log(); add note about being derived instead of direct.
* libm/common/sf_fma.c: Add casts to attempt to get correct results,
as well as comments pointing out problems with the implementation.
* libm/common/s_fma.c: Add fma() and fmaf() documentation.
* libm/common/sf_remquo.c: Incorrect quotient returns for large values
corrected by discarding existing function and replacing with Sun
verion, with some enhancements.
* libm/common/s_remquo.c: Ditto. Add remquo() and remquof()
documentation.
* libm/common/s_fmax.c: Add fmax() and fmaxf() documentation.
* libm/common/s_fmin.c: Add fmin() and fminf() documentation.
* libm/common/s_fdim.c: Return NAN for NAN arg, add fdim() and fdimf()
documentation.
* libm/common/sf_fdim.c: Return NAN for NAN arg, HUGE_VALF for inf arg.
* libm/common/s_trunc.c: Add trunc() and truncf() documentation.
* libm/common/s_rint.c: Add rint() and rintf() documentation.
* libm/common/s_round.c: Add round() and roundf() documentation.
* libm/common/s_scalbn.c: Add scalbln() and scalblnf() documentation.
* libm/common/s_infinity.c: Add infinity() and infinityf()
documentation.
* libm/common/s_lround.c: Add lround(), lroundf(), llround(), and
llroundf() documentation.
* libm/common/s_lrint.c: Add lrint(), lrintf(), llrint(), and llrintf()
documentation.
* libm/common/isgreater.c: New file for documenting math.h function-like
macros isgreater(), isgreaterequal(), isless(), islessequal(),
islessgreater(), and isunordered().
* libm/common/s_isnan.c: Add documentation for function-like macros
fpclassify(), isfinite(), isinf(), isnan(), and isnormal().
* libm/common/s_nearbyint.c: Add nearbyint() and nearbyintf()
documentation.
* libm/common/Makefile.am: Add s_llround.c (src); sf_llround.c (fsrc);
s_fdim.def, s_fma.def, s_fmax.def, s_fmin.def,
s_logb.def, s_lrint.def, s_lround.def, s_nearbyint.def, s_remquo.def,
s_rint.def, s_round.def, s_signbit.def, s_trunc.def, and
isgreater.def (chobj);
re-name all existing chew files (chobj) to match source file base
names (put in underscores), delete all special targets for chew files
(leaving all to be generated by rule).
* libm/common/Makefile.in: regenerate.
* libm/math/w_exp2.c: Add "base 2" to documentation description (and
delete TRAD_SYNOPSIS).
* libm/math/w_gamma.c: Add tgamma() and tgammaf() documentation, along
with some history behind the function names.
* libm/math/math.tex: Add includes for newly-added documentation (see
.def additions to common/Makefile.am and math/Makefile.am in this
ChangeLog list), adjusted existing .def file names to match source file
base names (added underscores); add mention of HUGE_VALF; rename
"Version of library" section to "Error Handling" and add some text
about floating-point exception; added section "Standards Compliance And
Portability".
* libm/math/Makefile.am: Add w_exp2.def (chobj);
re-name all existing chew files (chobj) to match source file base
names, delete all special targets for chew files (leaving all to be
generated by rule).
* libm/math/Makefile.in: regenerated
* doc/makedoc.c: Change silent ignoring of commands < 5 characters
to a failure when reading macro file for commands < 4 characters;
add -v (verbose) option for printing some debugging information;
get rid of spurious translation of "@*" to "*" (no source files used @*,
so no existing doc pages were affected); clean up some compiler
warnings.
* doc/doc.str: add BUGS and SEEALSO sections (to match texi2pod.pl
which has them); Remove ITEM command (redundant with makedoc built-in
"o", not used in any present source file so nothing is lost, anyway).
* HOWTO: New file to hold information for maintainers regarding how
to do things. Initial sections on documentation and ELIX levels.
118 lines
6.0 KiB
Plaintext
118 lines
6.0 KiB
Plaintext
This HOWTO file contains notes for maintainers and contributors to Newlib.
|
|
For information on using Newlib (building, installing), see README. (In
|
|
particular, the "Regenerating Configuration Files" section in README is of
|
|
interest to both users and contributors.)
|
|
|
|
(This file could probably use some other "sections" in addition to the
|
|
initially-provided sections. Please help by adding as appropriate.)
|
|
|
|
DOCUMENTATION
|
|
=============
|
|
|
|
All the documentation for Newlib comes as part of the machine-readable
|
|
distribution. Functions are documented in the source files, although not
|
|
every file contains documentation, as many functions share manual page
|
|
information. For example, lround(), lroundf(), llround(), and llroundf()
|
|
share a single man page, which is in the source for lround(). The documentation
|
|
is written partially in a custom format and partially in Texinfo format.
|
|
|
|
The custom part comprises makedoc.c and doc.str, both of which are in the
|
|
doc directory. doc.str is a macro file that can be used to define things to
|
|
be done by makedoc, using building blocks that are built into makedoc.c.
|
|
The basic function of makedoc is two-fold. First, it recognizes comments in
|
|
the proper format to pull out of source files. Second, it adds some Texinfo
|
|
commands as well as translating certain sequences into the appropriate
|
|
Texinfo commands. Refer to makedoc.c and doc.str for what these are.
|
|
(makedoc.c is not particularly-well commented.) Another way to see how they
|
|
work is to simply examine the source files with documentation comments.
|
|
|
|
(A couple of examples that use some of the fancier options:
|
|
libm/common/s_isnan.c ("o+" variable-"bullet" list),
|
|
libc/stdio/sprintf.c ("O+" bullet list; "." for example code).)
|
|
|
|
In addition to the makedoc.c stuff, Texinfo commands can be directly
|
|
used. Texinfo is a documentation system that uses a single source file to
|
|
produce both on-line information and a printed manual. You can use one of the
|
|
Info formatting commands to create the on-line version of the documentation
|
|
and TeX (or `texi2roff') to typeset the printed version. While Newlib contains
|
|
a copy of the texinfo package (texinfo.tex), the manual for it is not
|
|
included. The latest one may be found at
|
|
|
|
http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html
|
|
|
|
(which could be for a newer version of texinfo.tex than is included in Newlib).
|
|
|
|
In addition to Texinfo commands, straight TeX commands can also be used,
|
|
but these, however, should be carefully limited and be given alternates for
|
|
when a non-printed manual is produced--such as when info pages are produced.
|
|
For an example of this kind of usage, see libm/common/s_logb.c.
|
|
|
|
Please note that most files with documentation contain both an
|
|
ANSI_SYNOPSIS and a TRAD_SYNOPSIS section. The TRAD_SYNOPSIS section gets
|
|
deleted (since at least 2000) by makedoc, so when working on files these
|
|
can safely be deleted and if you're making a new file, there is no need
|
|
to add the TRAD_SYNOPSIS section.
|
|
|
|
If writing a new function that requires documentation, the required
|
|
sections are FUNCTION, INDEX, ANSI_SYNOPSIS (or SYNOPSIS), DESCRIPTION, RETURNS,
|
|
and PORTABILITY. BUGS and SEEALSO should be added as appropriate.
|
|
|
|
Source files which contain documentation are processed into ".def"
|
|
files with the extracted information. These .def files are noted in the
|
|
makefiles as either CHEWOUT_FILES in the libc makefiles or chobj in the libm
|
|
makefiles. These .def files need to be included into an appropriate .tex
|
|
file for inclusion in the manuals (one each for libc and libm). Pay special
|
|
attention under libc, as the manual is arranged by header file name, but not
|
|
all header files are represented by directories (e.g. wcsftime.c is found
|
|
under libc/time, but goes under wchar.h in the manual.)
|
|
|
|
In summary, to add new documentation:
|
|
|
|
1. Add properly-formatted comments to source file (e.g. src.c);
|
|
2. add "chewout" file to list in Makefile.am (CHEWOUT_FILES in libc or chobj in
|
|
libm) (e.g. src.def), re-generate Makefile.in;
|
|
3. add file to something.tex;
|
|
4. make ChangeLog entry and generate patch.
|
|
|
|
EL/IX (ELIX_LEVEL_n, ELIX_n_SOURCES)
|
|
====================================
|
|
|
|
Some of the Makefiles contain definitions of ELIX_LEVEL_1 ... ELIX_LEVEL_4,
|
|
and corresponding definitions for ELIX_1_SOURCES ... ELIX_4_SOURCES.
|
|
These are referring to the EL/IX standards created by Red Hat for the
|
|
purpose of Linux-based open standards for embedded development. In brief,
|
|
the intent is to define multiple levels for API functions that allows the
|
|
user to size the library appropriately for their application--at least in
|
|
terms of the predefined lists. For full details, refer to the EL/IX home
|
|
page at http://sources.redhat.com/elix/. The likely best way to tell how to
|
|
classify any new functions in terms of needing an ELIX level qualification
|
|
is to ask Jeff Johnston. To see how it works and try classification on your
|
|
own, refer to the API specification on the web site,
|
|
|
|
http://sources.redhat.com/elix/api/current/api.pdf.
|
|
|
|
(Unfortunately, it is not complete with respect to either the C99 or POSIX
|
|
standards, so particular C and POSIX functions may or may not be found.)
|
|
|
|
The following definitions of the levels are from the (draft) standard.
|
|
|
|
Level 1
|
|
RTOS compatible layer. Functions available in both Linux and a
|
|
typical deeply embedded operating system (eCos, RTEMS, VxWorks, pSOS, VRTX32,
|
|
etc.). Some functions may have reduced or modified semantics.
|
|
|
|
Level 2
|
|
Linux single process only. Includes level 1 plus any functions from Linux
|
|
that are not easily implemented on an RTOS. Also full implementations of
|
|
reduced functions in Level 1.
|
|
|
|
Level 3
|
|
Linux multiprocess for embedded applications. This is basically POSIX.1
|
|
with some of the functions that are obviously not for embedded applications
|
|
(such as job control) removed.
|
|
|
|
Level 4
|
|
Full POSIX or Linux compliance. Essentially these are functions that are
|
|
present in a standard Linux kernel but are irrelevant to an embedded system.
|
|
These functions do not form part of the EL/IX API.
|