From 3ed024dcb2f874e9a6a1eac6142a0864eac33460 Mon Sep 17 00:00:00 2001
From: Jeff Johnston <jjohnstn@redhat.com>
Date: Wed, 25 Mar 2009 21:16:04 +0000
Subject: [PATCH] 2009-03-25 Craig Howland <howland@LGSInnovations.com>
* 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.
---
newlib/HOWTO | 117 +++++++++++++++++++++++++++++++++++++++++++
newlib/doc/doc.str | 17 ++-----
newlib/doc/makedoc.c | 76 +++++++++++++++-------------
3 files changed, 163 insertions(+), 47 deletions(-)
create mode 100644 newlib/HOWTO
diff --git a/newlib/HOWTO b/newlib/HOWTO
new file mode 100644
index 000000000..6a0f2a92f
--- /dev/null
+++ b/newlib/HOWTO
@@ -0,0 +1,117 @@
+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.
diff --git a/newlib/doc/doc.str b/newlib/doc/doc.str
index 4d557c6f5..51ecef7f4 100644
--- a/newlib/doc/doc.str
+++ b/newlib/doc/doc.str
@@ -22,10 +22,6 @@
quickref
;
-
-: ITEM
- "@item " catstr ;
-
: EXAMPLE
skip_past_newline
@@ -55,7 +51,6 @@
;
-
: ANSI_SYNOPSIS
skip_past_newline
"@strong{Synopsis}\n" catstr
@@ -137,8 +132,6 @@
bodytext
;
-
-
: DESCRIPTION
"@strong{Description}@*\n" catstr subhead ;
@@ -148,31 +141,29 @@
: ERRORS
"@strong{Errors}@*\n" catstr subhead ;
-
: PORTABILITY
"@strong{Portability}@*\n" catstr subhead ;
+: BUGS
+ "@strong{Bugs}@*\n" catstr subhead ;
: WARNINGS
"@strong{Warnings}@*\n" catstr subhead ;
-
+: SEEALSO
+ "@strong{See Also}@*\n" catstr subhead ;
: INTERNAL_FUNCTION
func ;
-
: INTERNAL_DEFINITION
func ;
-
: INTERNAL
func ;
: TYPEDEF
FUNCTION ;
-
-
: NEWPAGE
"@page\n" catstr subhead ;
diff --git a/newlib/doc/makedoc.c b/newlib/doc/makedoc.c
index 00ff75c42..0bbffb66b 100644
--- a/newlib/doc/makedoc.c
+++ b/newlib/doc/makedoc.c
@@ -39,12 +39,15 @@ There is no
#include <stdio.h>
#include <stdlib.h>
#include <ctype.h>
+#include <string.h>
#define DEF_SIZE 5000
#define STACK 50
+#define MIN_CMDLEN 4 /* Minimum length of a command */
int internal_wanted;
int internal_mode;
+int Verbose=0;
@@ -212,7 +215,7 @@ string_type *tos;
unsigned int idx = 0; /* Pos in input buffer */
string_type *ptr; /* and the buffer */
-typedef void (*stinst_type)();
+typedef void (*stinst_type)(NOARGS);
stinst_type *pc;
stinst_type sstack[STACK];
stinst_type *ssp = &sstack[0];
@@ -234,7 +237,7 @@ struct dict_struct
};
typedef struct dict_struct dict_type;
-#define WORD(x) static void x()
+#define WORD(x) static void x(NOARGS)
static void DEFUN(exec,(word),
dict_type *word)
@@ -451,7 +454,6 @@ WORD(translatecomments)
WORD(quickref)
{
string_type *nos = tos-1;
- unsigned int scan=0;
unsigned int nosscan = 0;
unsigned int idx = 0;
@@ -487,6 +489,7 @@ WORD(quickref)
}
+#if 0
/* turn everything not starting with a . into a comment */
WORD(manglecomments)
@@ -520,6 +523,7 @@ WORD(manglecomments)
pc++;
}
+#endif
/* Mod tos so that only lines with leading dots remain */
static void
@@ -640,12 +644,15 @@ WORD(courierize)
}
/*
+bulletize: look for bullet item commands at start of line
+ Bullet list:
O+ emit @itemize @bullet
- OO emit @item
+ o emit @item [note lowercase]
O- emit @end itemize
+ Variable label list:
o+ emit @table @code
- oo @item
+ o emit @item
o- emit @end table
*/
@@ -653,19 +660,10 @@ WORD(courierize)
WORD(bulletize)
{
unsigned int idx = 0;
- int on = 0;
string_type out;
init_string(&out);
while (at(tos, idx)) {
- if (at(tos, idx) == '@' &&
- at(tos, idx+1) == '*')
- {
- cattext(&out,"*");
- idx+=2;
- }
-
- else
if (at(tos, idx) == '\n' && at(tos, idx+1) == 'o')
{
if (at(tos,idx+2) == '+') {
@@ -787,7 +785,10 @@ DEFUN( iscommand,(ptr, idx),
}
else if(at(ptr,idx) == '\n')
{
- if (len >4) return 1;
+ /* The length check will never fail on a real command
+ * because the commands are screened as the definitions file
+ * is read. */
+ if (len >= MIN_CMDLEN) return 1;
return 0;
}
else return 0;
@@ -797,6 +798,7 @@ DEFUN( iscommand,(ptr, idx),
}
+unsigned int
DEFUN(copy_past_newline,(ptr, idx, dst),
string_type *ptr AND
unsigned int idx AND
@@ -833,7 +835,6 @@ WORD(kill_bogus_lines)
{
int sl ;
- int nl = 0;
int idx = 0;
int c;
int dot = 0 ;
@@ -1162,9 +1163,6 @@ static void DEFUN_VOID(perform)
/* It's worth looking through the command list */
if (iscommand(ptr, idx))
{
- unsigned int i;
- int found = 0;
-
char *next;
dict_type *word ;
@@ -1178,6 +1176,7 @@ static void DEFUN_VOID(perform)
if (word)
{
+ if(Verbose) fprintf(stderr, "CMD '%s'\n", word->word);
exec(word);
}
else
@@ -1234,19 +1233,13 @@ return entry->code_end++;
void
DEFUN(add_intrinsic,(name, func),
char *name AND
- void (*func)())
+ void (*func)(NOARGS))
{
dict_type *new = newentry(name);
add_to_definition(new, func);
add_to_definition(new, 0);
}
-WORD(push_addr)
-{
-
-
-}
-
void
DEFUN(add_var,(name),
char *name)
@@ -1261,13 +1254,12 @@ DEFUN(add_var,(name),
-void
+int
DEFUN(compile, (string),
char *string)
{
- int jstack[STACK];
- int *jptr = jstack;
+ int ret=0;
/* add words to the dictionary */
char *word;
string = nextword(string, &word);
@@ -1275,18 +1267,24 @@ DEFUN(compile, (string),
{
if (strcmp(word,"var")==0)
{
- string=nextword(string, &word);
+ string=nextword(string, &word);
add_var(word);
- string=nextword(string, &word);
+ string=nextword(string, &word);
}
-else
+ else
if (word[0] == ':')
{
dict_type *ptr;
/* Compile a word and add to dictionary */
string = nextword(string, &word);
+ if(Verbose) fprintf(stderr, "Found command '%s'\n", word);
+ if(strlen(word) < MIN_CMDLEN) {
+ fprintf(stderr, "ERROR: Command '%s' is too short ", word);
+ fprintf(stderr, "(MIN_CMDLEN is %d)\n", MIN_CMDLEN);
+ ret++;
+ }
ptr = newentry(word);
string = nextword(string, &word);
@@ -1330,9 +1328,11 @@ else
else
{
fprintf(stderr,"syntax error at %s\n",string-1);
+ ret++;
}
}
+return(ret);
}
@@ -1378,11 +1378,13 @@ static void DEFUN(read_in, (str, file),
}
+#if 0
static void DEFUN_VOID(usage)
{
- fprintf(stderr,"usage: -[d|i|g] <file >file\n");
+ fprintf(stderr,"usage: -[i|v] -f macrofile <file >file\n");
exit(33);
}
+#endif
int DEFUN(main,(ac,av),
int ac AND
@@ -1446,16 +1448,22 @@ char *av[])
fprintf(stderr,"Can't open the input file %s\n",av[i+1]);
return 33;
}
+ if(Verbose) fprintf(stderr, "Reading -f '%s'\n", av[i+1]);
read_in(&b, f);
- compile(b.ptr);
+ if( compile(b.ptr) ) { fclose(f); exit(1); }
perform();
+ fclose(f);
}
else if (av[i][1] == 'i')
{
internal_wanted = 1;
}
+ else if (av[i][1] == 'v')
+ {
+ Verbose++;
+ }
}
}